harnex 0.29.0 → 0.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72eab06bb2287cadb7e9e2f525350b981571717088de593d9ad5225ca9aa324e
-  data.tar.gz: 6a2fecf3083f015e9ecc90d658a4797439740e21985fecdd3515e98f179f16d1
+  metadata.gz: e36a59564be22ba55cda2815e3e72b59b887bb2a4e0417be776295ef1cb10b82
+  data.tar.gz: 0a9b1355a5bc153e4d6fdd6ef79df81f022c5b6a75f97de0a8f91ef52353e526
 SHA512:
-  metadata.gz: e662b7bb01799d6a8faf1ff62efb1b4353dd6f684ab43f250bcf783981189709a2c60871a8cf8e3c55772e2d233131880ddd2324d8bbe47f2ac2766d5d09ef91
-  data.tar.gz: 4de10a7bed0959e709c2f99df9dda5dac4ccdc79054919d4cade8780c712f3f2ad1a5b322586a01dadf43637de52ec731299ca8a874f13e156ff31480b02357b
+  metadata.gz: 1794b1c8190bf40109732a821470d9a24772be9e68e46b9c49732ac46bd24fb73a88d07d0097dece3ec43e3b164932903d69ffda7fa6b4f18b244989990c8a52
+  data.tar.gz: 8163c5eb86dacb6174868459fcc9bba2fb87b66c503e61a96f38baefbe2ca93423df3a84fd07da626927402fe5432f4f541eec202a7b4cc4fde131e1b9ff7de4

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.29.1] - 2026-10-23 | 10:31 AM | IST
+
+Local-only fix release for #88: lanes in repos with a phase allowlist.
+
+### Fixed
+
+- In a repo whose `.harnex/config.json` phase allowlist has
+  `"policy": "reject"`, harnex refused every `delegate`, `ask --write` and
+  `reply` (`meta.phase (none) is not allowlisted`). The run behind a lane
+  is now tagged with phase `delegate` or `ask`. These are harnex's own
+  phases, like `preflight`, so every allowlist accepts them.
+- A lane that harnex refused before the worker started left a `failed`
+  record, so a retry under the same name failed with `lane NAME already
+  exists (failed)` until `discard`. Now a refused new lane leaves no record
+  and no brief. A refused `reply` keeps the state the lane's last turn left.
+  The next `delegate` under the same name also clears a record left this way
+  by 0.29.0.
+
+### Added
+
+- `harnex delegate --phase NAME` and `harnex ask --phase NAME` tag a lane
+  with a work phase such as `implement`. The repo allowlist checks a named
+  phase, and `reply` reuses it.
+
 ## [0.29.0] - 2026-10-22 | 06:08 PM | IST
 
 **The agent release.** harnex becomes a tool your coding agents use directly:

data/docs/configuration.md

@@ -42,6 +42,10 @@ The effective value is the first-class `harnex run --phase TEXT` value, or
 - Allowlisted phase: dispatches silently.
 - `policy: "warn"`: prints a warning and dispatches.
 - `policy: "reject"`: exits non-zero before spawn and writes no dispatch row.
+- Harnex's own phases always pass: `preflight` (the `harnex preflight` probe)
+  and the lane phases `delegate` and `ask`. A lane runs under its kind's
+  phase unless `harnex delegate --phase NAME` (or `harnex ask --phase NAME`)
+  names a work phase, which the allowlist then checks.
 
 The allowlist must be an array of non-empty strings. Policy must be `warn` or
 `reject`.

data/docs/lanes.md

@@ -74,6 +74,10 @@ cost, commits and the next commands.
   expected behavior and how to verify it.
 - **`--model provider/model`** and **`--effort low|medium|high`** pick the
   model; the default is Pi's own default model.
+- **`--phase NAME`** tags the lane's dispatch rows with a work phase (for
+  example `implement`). Without it the phase is `delegate` (`ask` for an ask),
+  which a repo's phase allowlist always accepts; a named phase is checked
+  against the allowlist (see [configuration](configuration.md)).
 
 ### Waiting, and long tasks
 

data/guides/01_dispatch.md

@@ -213,7 +213,8 @@ are present.
 Every dispatch writes one `dispatch_start` and one rich v2 `dispatch_end` row
 to the canonical repo/global dispatch stream, which is the only telemetry
 destination. Repo `.harnex/config.json` can warn on or reject non-canonical
-phase names before spawn.
+phase names before spawn; lanes (`delegate`, `ask`) and `preflight` are
+exempt unless a lane is given `--phase NAME`.
 
 Pi runs use structured RPC (`pi --mode rpc`) and require Pi >= 0.80.4; gate
 unattended work with `harnex doctor --adapter pi`. Harnex `--model` / `--effort`

data/lib/harnex/commands/ask.rb

@@ -33,6 +33,8 @@ module Harnex
                            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
+          --phase NAME     Tag the run with a repo work phase (with --write, checked
+                           against the repo's allowlist); default: ask
           --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
@@ -63,7 +65,7 @@ module Harnex
       @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,
+      @options = { model: nil, fallback_model: nil, effort: nil, phase: 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
@@ -99,7 +101,12 @@ module Harnex
       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?
+      if !result.empty?
+        Lanes.settle(lane, result["turn_result"] || {}, status.exitstatus)
+      elsif status.exitstatus != Waiter::DONE_EXIT_TIMEOUT
+        # Refused before the worker started (#88); 124 may still come up.
+        Lanes.forget(lane)
+      end
       [result, status.exitstatus]
     end
 
@@ -108,8 +115,8 @@ module Harnex
       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
+        "requested_model" => model, "effort" => @options[:effort], "phase" => @options[:phase],
+        "created_at" => Lanes.now, "launched_at" => Lanes.now, "state" => "running", "turns" => 0
       )
     end
 
@@ -126,7 +133,7 @@ module Harnex
       else
         argv += ["--context", question]
       end
-      argv += ["--auto-stop", "--wait-done", "--intent", INTENT]
+      argv += ["--auto-stop", "--wait-done", "--intent", INTENT, "--phase", @options[:phase] || INTENT]
       argv += ["--wait-timeout", @options[:timeout].to_s] if @options[:timeout]
       argv += ["--model", model] if model
       argv += ["--effort", @options[:effort]] if @options[:effort]
@@ -231,7 +238,7 @@ module Harnex
         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"
+        when "--model", "--effort", "--phase", "--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.

data/lib/harnex/commands/delegate.rb

@@ -23,6 +23,9 @@ module Harnex
           --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
+          --phase NAME     Tag the run with a repo work phase (checked against the
+                           repo's .harnex/config.json allowlist); default: delegate,
+                           which every allowlist accepts
           --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;
@@ -46,7 +49,7 @@ module Harnex
       @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,
+      @options = { worktree: nil, name: nil, cwd: nil, file: nil, model: nil, effort: nil, phase: nil, wait: true,
                    timeout: Lanes::DEFAULT_TIMEOUT, detach: false, json: false, help: false }
     end
 
@@ -90,7 +93,7 @@ module Harnex
       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
+        "phase" => @options[:phase], "created_at" => Lanes.now, "turns" => 0
       }
       if @options[:worktree]
         warn_uncommitted(root)
@@ -105,15 +108,18 @@ module Harnex
 
     # A lane that never started leaves nothing behind.
     def discard_unstarted
-      return unless @lane && @lane["worktree"] && @lane["turns"].to_i.zero?
+      return unless @lane && @lane["turns"].to_i.zero?
 
-      Lanes.remove_worktree(@lane, force: true)
-      @lane["state"] = "discarded"
-      Lanes.save(@lane)
+      Lanes.remove_worktree(@lane, force: true) if @lane["worktree"]
+      Lanes.forget(@lane)
     end
 
     def ensure_free!(root, name)
       existing = Lanes.load(root, name)
+      if Lanes.never_started?(existing)
+        Lanes.forget(existing)
+        existing = nil
+      end
       if Lanes.open?(existing)
         raise OptionParser::InvalidArgument,
               "lane #{name} already exists (#{existing['state']}): follow up with `harnex reply #{name} \"...\"`, " \
@@ -165,7 +171,7 @@ module Harnex
         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"
+        when "--worktree", "--name", "--cwd", "--file", "--model", "--effort", "--phase"
           @options[arg.delete_prefix("--").to_sym] = value(index += 1, arg)
         when "--timeout", "--wait-timeout"
           @options[:timeout] = Lanes.parse_timeout(value(index += 1, arg))

data/lib/harnex/commands/run.rb

@@ -486,8 +486,9 @@ module Harnex
       metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
       phase = metadata["phase"].to_s
       allowlist = phase_config.fetch("allowlist")
-      # `harnex preflight` tags its own probe; repo phase policy governs work.
-      return if allowlist.include?(phase) || phase == Preflight::PHASE
+      # Harnex tags its own runs (the `harnex preflight` probe, lanes); repo
+      # phase policy governs work phases.
+      return if allowlist.include?(phase) || phase == Preflight::PHASE || Lanes::PHASES.include?(phase)
 
       policy = phase_config.fetch("policy")
       message = "harnex run: meta.phase #{phase.empty? ? '(none)' : phase.inspect} " \

data/lib/harnex/lanes.rb

@@ -19,6 +19,9 @@ module Harnex
     WORKTREES_DIR = File.join(".harnex", "worktrees").freeze
     CLOSED_STATES = %w[landed discarded].freeze
     DEFAULT_TIMEOUT = 540
+    # A lane's run is tagged meta.phase = its kind unless the caller names a
+    # phase; repo phase allowlists exempt these harnex-owned phases (#88).
+    PHASES = %w[delegate ask].freeze
 
     module_function
 
@@ -60,6 +63,16 @@ module Harnex
       lane && !CLOSED_STATES.include?(lane["state"])
     end
 
+    # Older harnex kept the record of a lane refused before it started (#88).
+    def never_started?(lane)
+      lane && lane["state"] == "failed" && lane["turns"].to_i.zero? && !live?(lane)
+    end
+
+    def forget(lane)
+      FileUtils.rm_f(path(lane["repo_root"], lane["name"]))
+      FileUtils.rm_f(brief_path(lane["repo_root"], lane["name"]))
+    end
+
     # A name resolves to this repo's lane first, then to the only lane
     # anywhere with that name.
     def resolve(name, from: Dir.pwd)
@@ -227,8 +240,7 @@ module Harnex
         closed_at = Time.iso8601((lane["landed_at"] || lane["updated_at"]).to_s)
         next if closed_at > cutoff
 
-        FileUtils.rm_f(path(lane["repo_root"], lane["name"]))
-        FileUtils.rm_f(File.join(dir, "briefs", "#{Harnex.repo_key(lane['repo_root'])}--#{lane['name']}.md"))
+        forget(lane)
       rescue ArgumentError
         next
       end
@@ -253,8 +265,12 @@ module Harnex
 
     # ---- briefs ------------------------------------------------------------
 
+    def brief_path(repo_root, name)
+      File.join(dir, "briefs", "#{Harnex.repo_key(repo_root)}--#{name}.md")
+    end
+
     def write_brief(lane, task)
-      file = File.join(dir, "briefs", "#{Harnex.repo_key(lane['repo_root'])}--#{lane['name']}.md")
+      file = brief_path(lane["repo_root"], lane["name"])
       footer = if lane["branch"]
                  "You are working in a git worktree on branch #{lane['branch']}; the main checkout is not " \
                    "affected. When you are done, commit your changes on this branch, then reply with a short " \
@@ -275,6 +291,7 @@ module Harnex
     # done); without, returns [launch_payload, 0]. A launch that fails before
     # any result (bad flag, busy id, no tmux) raises with harnex's message.
     def launch(lane, harnex_command, context_args:, child_args: [], wait: true, timeout: DEFAULT_TIMEOUT, detach: false)
+      before = lane.slice(*RELAUNCH_KEYS)
       lane["launched_at"] = now
       lane["state"] = "running"
       lane.delete("after_seq")
@@ -283,7 +300,8 @@ module Harnex
 
       argv = harnex_command + ["run", "pi", "--id", lane["name"]]
       argv += detach ? ["--detach"] : ["--tmux", lane["name"]]
-      argv += ["--cwd", lane["cwd"], "--root", lane["run_root"], "--auto-stop", "--intent", lane["kind"]]
+      argv += ["--cwd", lane["cwd"], "--root", lane["run_root"], "--auto-stop", "--intent", lane["kind"],
+               "--phase", lane["phase"] || lane["kind"]]
       argv += context_args
       argv += ["--model", lane["requested_model"]] if lane["requested_model"]
       argv += ["--effort", lane["effort"]] if lane["effort"]
@@ -292,9 +310,8 @@ module Harnex
       stdout, stderr, status = Open3.capture3(*argv)
       payload = last_json(stdout)
       if payload.empty?
-        lane["state"] = "failed"
-        lane["last_error"] = stderr.strip.lines.last.to_s.strip
-        save(lane)
+        # 124: the worker did not register in time and may still come up.
+        status.exitstatus == Waiter::DONE_EXIT_TIMEOUT ? fail_launch(lane, stderr) : unlaunch(lane, before)
         raise LaunchError, "harnex could not start lane #{lane['name']}: #{stderr.strip.lines.last(3).join.strip}"
       end
       return [payload, 0] unless wait
@@ -302,6 +319,24 @@ module Harnex
       [payload["turn_result"] || payload, status.exitstatus]
     end
 
+    RELAUNCH_KEYS = %w[state launched_at after_seq last_error].freeze
+
+    # A launch refused before the worker started (a bad flag, repo phase
+    # policy, a busy id) leaves no trace: a new lane's record goes, and a
+    # resumed lane keeps what its last turn left.
+    def unlaunch(lane, before)
+      return forget(lane) if lane["turns"].to_i.zero?
+
+      RELAUNCH_KEYS.each { |key| before.key?(key) ? lane[key] = before[key] : lane.delete(key) }
+      save(lane)
+    end
+
+    def fail_launch(lane, stderr)
+      lane["state"] = "failed"
+      lane["last_error"] = stderr.strip.lines.last.to_s.strip
+      save(lane)
+    end
+
     def wait(lane, harnex_command, timeout: DEFAULT_TIMEOUT)
       argv = harnex_command + ["wait", "--id", lane["name"], "--repo", lane["run_root"], "--until", "done",
                                "--since", lane["launched_at"]]

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.29.0"
-  RELEASE_DATE = "2026-10-22"
+  VERSION = "0.29.1"
+  RELEASE_DATE = "2026-10-23"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.29.1
 platform: ruby
 authors:
 - Jikku Jose
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies: []
 description: 'Hand questions and tasks to Pi workers in visible tmux windows and get
   the result back in one call: lanes in git worktrees, follow-ups that keep context,