harnex 0.30.0 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4b50e456b0b9be717e037a0596b942273e2e4c192b80d697fc502a66cc4c220
-  data.tar.gz: 77ed9e03656bfff5f68064bb4dcb64f898d1de6b5d599ad30450ac51f8a1938e
+  metadata.gz: e3869562568a9927b6a413b5536ee9c489940ce0a8cf9ac6c001072b005ae760
+  data.tar.gz: 1203d0e9e327d56ccb63a119bc27489c417dce551e6be530772b2477e6f592b2
 SHA512:
-  metadata.gz: 85ca4102b12fe2a0e109c1fdfc643c96d80677b267c0b658cb4ff5787a72075e0d77e9d98a29bf401fa5975502cfc5fca891fe62c63ef51a92b8f626e2c60d04
-  data.tar.gz: 39b143e75ade8b68254742f6ea23eee43fde615c01de9c273d221b681b8b913f7c35e87b6bf9a79f84e290602790641fdb5a96e84c7a75fedad602b1ef6718d6
+  metadata.gz: 5f445333438f47be5c9f8f8eef6a90c3ce4844d6d4c398ae9f9a1568d4750de3313f741266b325b07d01fb941599473b6b143c827b34aa8608cab47a7f2bd1db
+  data.tar.gz: f5bc3dde8e4ab3b666989418293ce304d53dbcbd4752baf7d17ad1afad86e39af2d8b56bcf28ace274caf5440892ac7111e4fb8dfd02581e9de38757a6659d7e

data/CHANGELOG.md

@@ -1,8 +1,28 @@
 # Changelog
 
+## [0.30.1] - 2026-10-28 | 11:16 AM | +04
+
+Holm Queue 174 lost a night to dead lanes reading `running` and refusals
+reading "Unknown error": #93.
+
+### Fixed
+
+- **Settled lanes no longer read `running` in machine listings** (#93).
+  `harnex lanes --json` reports `done`/`failed` independently of
+  `collected`; listing does not collect results. The table, which MCP
+  `lanes` also returns, keeps its wording, including `finished, uncollected`.
+- **Pi provider errors have actionable outcomes** (#93). Refusal errors
+  (`cyber_policy`, content filter/policy, cybersecurity-risk flags) settle as
+  `policy_refusal`; retry guidance requires a rephrased brief or another
+  route. Pi's exact `Unknown error (no error details in response)` settles as
+  `provider_error_unexplained`, with guidance to inspect provider/gateway
+  logs before retrying. Neither suggests continuing the same task unchanged.
+  Both classes remain intact in owner-watch events and count toward the
+  default orchestration failure budget. `provider_capacity` is unchanged.
+
 ## [0.30.0] - 2026-10-25 | 02:55 AM | IST
 
-Holm's first nights with lanes (Holm Queue 167): #89–#92. Local install.
+Holm's first nights with lanes (Holm Queue 167): #89–#92. Published to RubyGems.
 
 ### Fixed
 

data/TECHNICAL.md

@@ -423,7 +423,10 @@ not a new runtime.
   base sha, owner (`CLAUDE_CODE_SESSION_ID`/`PI_SESSION_ID`), requested model,
   Pi `agent_session_id`, accumulated cost, launch time and the last turn's result.
   States: `running` (a turn is out and uncollected), `done`, `failed`, `landed`,
-  `discarded`.
+  `discarded`. `lanes --json` and MCP `lanes` project current settlement from
+  task events (or fresh terminal evidence): `done`/`failed` even before
+  collection, with separate `collected` and process-liveness `live` fields.
+  Listing is read-only; pending results and the table wording are unchanged.
 - **Launching:** the verbs shell out to the low-level CLI. `delegate` runs
   `harnex run pi --id NAME --tmux NAME --cwd WORKDIR --root ROOT --auto-stop`
   with a brief file (`--context-file`); with `--wait-done` it blocks on the
@@ -436,7 +439,12 @@ not a new runtime.
   <agent_session_id>`, so Pi resumes the conversation.
 - **Settling:** after a turn, the lane reads the launch's `usage` event (cost,
   `agent_session_id`) and records the result; the footer adds commits and a
-  diffstat from git (`base_sha..HEAD`).
+  diffstat from git (`base_sha..HEAD`). Pi error text can classify
+  `policy_refusal` (retry with a rephrased brief or another route) or
+  `provider_error_unexplained` (inspect provider/gateway logs first). These
+  failure classes are preserved in `watch --owner`; `provider_capacity`
+  retains its adapter-retries-exhausted meaning. Full vocabulary:
+  [dispatch telemetry](docs/dispatch-telemetry.md).
 - **Worktrees:** `.harnex/worktrees/NAME` on branch `harnex/NAME`; `.harnex/`
   is added to `<git-common-dir>/info/exclude` on the first write.
   `land` merges with `git merge --no-edit`, leaves conflicts in progress, and

data/docs/configuration.md

@@ -50,6 +50,28 @@ The effective value is the first-class `harnex run --phase TEXT` value, or
 The allowlist must be an array of non-empty strings. Policy must be `warn` or
 `reject`.
 
+## Lane worktrees
+
+`harnex delegate --worktree NAME` creates `.harnex/worktrees/NAME` on branch
+`harnex/NAME`. Repositories that keep worktrees elsewhere can set templates:
+
+```json
+{
+  "lanes": {
+    "worktree_path": "../night-{mm}{dd}_{name}",
+    "branch": "night/{mm}{dd}_{name}"
+  }
+}
+```
+
+- Placeholders: `{name}` (the lane), `{yyyy}`, `{mm}`, `{dd}` (the day the
+  lane starts). Each template must contain `{name}`.
+- `worktree_path` is relative to the main checkout; `branch` must be a valid
+  branch name.
+- Either key may be left out to keep its default. `land` and `discard` follow
+  each lane's recorded path and branch, so changing the templates does not
+  strand lanes already started. See [Lanes](lanes.md).
+
 ## Events, output, and receipt retention
 
 Per-session event JSONL, output transcripts, and generated proof receipts live

data/docs/dispatch-telemetry.md

@@ -345,10 +345,16 @@ facts prove the delta, not semantic quality or human authorship.
 - **Completion:** `completed_with_proof`, `completed_with_activity`.
 - **Proof defects:** `completed_no_activity`, `report_missing`,
   `report_invalid`, `report_rejected`.
-- **Process:** `task_failed` (the turn failed), `provider_capacity` (the turn
-  failed after the adapter's own provider retries ran out, from Pi's
-  structured `auto_retry_end success:false`; capacity or rate limits rather
-  than the work), `boot_failure` (structured
+- **Provider:** `provider_capacity` (the turn failed after the adapter's own
+  provider retries ran out, from Pi's structured `auto_retry_end success:false`;
+  capacity or rate limits rather than the work), `policy_refusal` (Pi's error
+  text names `cyber_policy`, content filter/policy, or a cybersecurity-risk
+  flag; retry needs a rephrased brief or another route),
+  `provider_error_unexplained` (Pi's exact `Unknown error (no error details in
+  response)`; inspect provider/gateway logs before retrying). Explicit error
+  classes take precedence over retry exhaustion; they do not infer a refusal
+  from an unexplained error. `watch --owner` carries these classes unchanged.
+- **Process:** `task_failed` (the turn failed), `boot_failure` (structured
   transport died before its first turn), `permission_prompt` (ended on a
   trust/confirmation prompt the adapter recognizes), `timeout` (`--max-runtime`
   stopped running work, or exit 124), `stopped_by_caller` (a manual stop
@@ -375,7 +381,8 @@ initial workers do not join families. Start rows are not counted. An optional
 adds a `failure_budget` verdict and exits 3 once N fatal failures are counted
 (1 is an error, 2 a usage error; a missing `--dispatch` file is an error).
 By default the fatal classes are `completed_no_activity`, `task_failed`,
-`provider_capacity`, `boot_failure`, `permission_prompt`, `timeout`, and `process_failed`; proof
+`provider_capacity`, `policy_refusal`, `provider_error_unexplained`,
+`boot_failure`, `permission_prompt`, `timeout`, and `process_failed`; proof
 defects, caller stops and `unknown` are not fatal.
 Harnex supplies the ledger only: the caller decides what to do on a breach.
 

data/docs/lanes.md

@@ -199,7 +199,14 @@ interjections.
 For provider and model failures (not found, rate limited, out of capacity) the
 footer suggests continuing on Pi's default model. `reply --model` resumes the
 same session, so the task is not lost. For `ask`, `--fallback-model` does this
-automatically.
+automatically on `provider_capacity` only.
+
+A provider refusal is different: `policy_refusal` means the provider refused
+the content, so a retry needs a rephrased brief or another route. Do not send
+"Continue the same task" unchanged. `provider_error_unexplained` means Pi
+reported exactly `Unknown error (no error details in response)`; read the
+provider/gateway logs before retrying. Harnex does not infer a policy refusal
+when Pi supplies no details.
 
 ## Watching a worker
 
@@ -214,7 +221,12 @@ truncate  done                   2m03s  gpt-5.1  harnex/truncate  harnex land tr
 ```
 
 A working lane shows the tool it is running right now (tool names only; harnex
-never records tool arguments). `harnex pane --id NAME --lines 40` captures the
+never records tool arguments). `harnex lanes --json` and MCP `lanes` return
+current settlement (`done`/`failed` even before collection), a separate
+`collected` boolean, and process-liveness `live`. `collected: false` means
+`harnex result` still needs to collect the turn; listing does not do that.
+The table keeps `finished, uncollected` for those finished workers.
+`harnex pane --id NAME --lines 40` captures the
 worker's tmux window, and the window itself is always there to watch.
 
 ## Where things live

data/docs/mcp.md

@@ -17,8 +17,12 @@ servers when a session starts. `harnex doctor` reports the registrations under
 
 ## Tools
 
-Each tool runs the matching CLI command and returns its text: the worker's
-reply followed by the `── NAME:` footer.
+Each tool runs the matching CLI command and returns its text: normally the
+worker's reply followed by the `── NAME:` footer. `lanes` returns the
+`harnex lanes` table, with each worker's live activity; a settled worker reads
+"finished, uncollected" until its result is collected. Scripts use
+`harnex lanes --json`, whose `state` is `done`/`failed` for a settled worker
+(never `running`), with separate `collected` and `live` fields.
 
 | Tool | Arguments | Does |
 | --- | --- | --- |
@@ -28,7 +32,7 @@ reply followed by the `── NAME:` footer.
 | `reply` | `name`, `message`; `model`, `wait`, `cwd`, `wait_minutes` | Follow-up to the same worker, which keeps its context |
 | `land` | `names` (optional); `cwd` | Merge worktree lanes, remove worktrees and branches |
 | `discard` | `names`; `cwd` | Drop lanes without merging |
-| `lanes` | `all`; `cwd` | Open lanes, what each worker is doing, the next step |
+| `lanes` | `all`; `cwd` | Open lane JSON: settled state, collection, liveness, model and branch |
 
 Arguments are forgiving: `prompt`, `brief` or `message` work for `task`;
 `prompt` or `query` for `question`; `lane` or `id` for `name`. `cwd` defaults

data/docs/pi-rpc.md

@@ -107,6 +107,15 @@ Harnex maps Pi events as follows:
 | `agent_settled` without an authoritative final stop reason | fail closed |
 | EOF, malformed JSON, or request timeout | disconnect/failure |
 
+A final Pi `error` with refusal text (`cyber_policy`, content filter/policy,
+"flagged for possible cybersecurity risk") settles as `policy_refusal`.
+A retry needs a rephrased brief or another route, not the same task unchanged.
+The exact `Unknown error (no error details in response)` settles as
+`provider_error_unexplained`: inspect provider/gateway logs before retrying;
+it is not evidence of a refusal. Both override exhausted adapter retries;
+otherwise `provider_capacity` keeps its existing retry-exhaustion behavior.
+These classes survive status, dispatch rows and `watch --owner` events.
+
 A forced send while Pi is busy is translated to a `prompt` with
 `streamingBehavior="steer"`; ordinary sends wait for the settled prompt state.
 This avoids sending a plain prompt that current Pi correctly rejects while

data/guides/04_monitoring.md

@@ -238,7 +238,10 @@ harnex watch --owner --stall-after 25m
   `session_id`, `repo`, `ts`, `work_state`, plus `outcome_class`,
   `receipt_path`, `elapsed_s`, `stall`, `reason` where they apply, and a
   readable `msg`. No heartbeats, so Claude Code's `Monitor` wakes only when
-  something needs a decision.
+  something needs a decision. Provider failures preserve `policy_refusal`
+  (rephrase the brief or use another route), `provider_error_unexplained`
+  (read provider/gateway logs before retrying), and `provider_capacity`
+  (adapter retries exhausted) as distinct outcome classes.
 - **Restarts:** a restarted stream re-announces `started` for running
   dispatches and delivers only results it has not delivered before (cursor
   under the owner's notifications directory). Delivery is not acceptance:

data/guides/06_claude.md

@@ -70,7 +70,12 @@ harnex reply word-count "Also add TextKit.char_count(text) with a test."
 A worker still on its turn takes the message as a follow-up. A finished lane
 is relaunched on its own Pi session, so the worker keeps everything it knew.
 After a provider-capacity failure, reply "Continue the same task from where
-you stopped", optionally with `--model OTHER`.
+you stopped", optionally with `--model OTHER`. Do not do that for
+`policy_refusal`: the provider refused the content, so retry with a rephrased
+brief or another route. For `provider_error_unexplained`, read the
+provider/gateway logs before retrying. `harnex lanes --json` and MCP `lanes`
+separate settled `state` (`done`/`failed`) from `collected` and process `live`;
+uncollected results are still available through `result`.
 
 ## Rules For Claude Code
 

data/lib/harnex/commands/ask.rb

@@ -216,6 +216,8 @@ module Harnex
         @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})")
+        hint = Lanes.provider_failure_hint("outcome" => turn["outcome_class"])
+        @err.puts("next: #{hint}") if hint
       end
       exit_code
     end

data/lib/harnex/commands/lanes.rb

@@ -34,7 +34,7 @@ module Harnex
       Lanes.sweep_merged(Lanes.main_root(Dir.pwd))
       lanes = selected
       if @argv.include?("--json")
-        @out.puts JSON.generate(lanes.map { |lane| lane.merge("live" => Lanes.live?(lane)) })
+        @out.puts JSON.generate(lanes.map { |lane| Lanes.snapshot(lane) })
       elsif lanes.empty?
         @out.puts "no lanes#{@argv.include?('--all') ? '' : ' in this repo'} (start one with `harnex delegate`)"
       else

data/lib/harnex/commands/orchestration.rb

@@ -51,7 +51,8 @@ module Harnex
         Worker outcome classes (dispatch row outcome.class):
           completed   completed_with_proof completed_with_activity
           proof       completed_no_activity* report_missing report_invalid report_rejected
-          process     task_failed* provider_capacity* boot_failure* permission_prompt*
+          provider    provider_capacity* policy_refusal* provider_error_unexplained*
+          process     task_failed* boot_failure* permission_prompt*
                       timeout* process_failed* stopped_by_caller
           fallback    unknown
         The budget is a ledger, not a breaker: enforcement stays with the caller.

data/lib/harnex/lanes.rb

@@ -11,8 +11,9 @@ module Harnex
   # harnex/<name>. A record under STATE_DIR/lanes lets `result`, `reply`,
   # `land` and `discard` find a lane by name from anywhere in its repo.
   #
-  # Record states: running (a turn is out and nobody has collected it),
-  # done, failed, landed, discarded.
+  # Internal record states: running (a turn is out and uncollected), done,
+  # failed, landed, discarded. Machine listings project the worker's settled
+  # state independently, with `collected` indicating the record's boundary.
   module Lanes
     NAME = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,47}\z/
     BRANCH_PREFIX = "harnex/".freeze
@@ -154,6 +155,57 @@ module Harnex
       !registry.nil? && Harnex.alive_pid?(registry["pid"])
     end
 
+    # #93: listing is read-only, not result collection. The record's running
+    # state still drives pending/result and the table's "finished, uncollected".
+    # Fence evidence to this launch and follow-up so a reused name cannot pick
+    # up an earlier turn. Settlement can precede process exit (Pi at prompt).
+    def snapshot(lane)
+      live = live?(lane)
+      view = lane.merge("live" => live, "collected" => lane["state"] != "running")
+      return view unless lane["state"] == "running"
+
+      %w[outcome last_error settled_at last_turn].each { |key| view.delete(key) }
+      event = events(lane).reverse.find do |row|
+        row.is_a?(Hash) && %w[task_complete task_failed work_turn agent_start].include?(row["type"]) &&
+          after?(row["ts"], lane["launched_at"]) &&
+          (!lane["after_seq"] || row["seq"].to_i > lane["after_seq"].to_i)
+      end
+      if event && %w[task_complete task_failed].include?(event["type"])
+        failed = event["type"] == "task_failed" ||
+                 (!event["status"].to_s.empty? && !%w[completed success succeeded].include?(event["status"]))
+        view.merge!("state" => failed ? "failed" : "done", "outcome" => event["outcome_class"] || event["status"],
+                    "settled_at" => event["ts"])
+        view["last_error"] = event["message"] || event["error"] if failed
+      elsif !live
+        # Process failures may exit without a task event. The canonical end
+        # row supplies their class; ignore old rows from a previous launch.
+        terminal = TerminalStatus.resolve(id: lane["name"], repo_root: lane["run_root"])
+        if terminal && terminal["terminal"] && after?(terminal["ended_at"], lane["launched_at"])
+          view.merge!("state" => terminal["work_state"] == "completed" ? "done" : "failed",
+                      "outcome" => terminal["outcome_class"], "settled_at" => terminal["ended_at"])
+        elsif (exit_status = fresh_exit_status(lane))
+          done = exit_status["task_complete"] == true ||
+                 (exit_status["task_failed"] != true && exit_status["exit_code"] == 0)
+          view.merge!("state" => done ? "done" : "failed", "outcome" => exit_status["outcome_class"],
+                      "settled_at" => exit_status["exited_at"])
+        end
+      end
+      view
+    end
+
+    def fresh_exit_status(lane)
+      path = Harnex.exit_status_path(lane["run_root"], lane["name"])
+      data = JSON.parse(File.read(path))
+      return nil unless data.is_a?(Hash)
+
+      # Exit timestamps have second precision; mtime also fences same-second
+      # relaunches so an earlier dispatch's leftover file cannot settle one.
+      since = Time.iso8601(lane["launched_at"].to_s)
+      data if File.mtime(path) >= since && after?(data["exited_at"], since.iso8601)
+    rescue Errno::ENOENT, JSON::ParserError, ArgumentError
+      nil
+    end
+
     # The live worker's activity snapshot (see ActivityTracker), or nil.
     def activity(lane)
       registry = Harnex.read_registry(lane["run_root"], lane["name"])
@@ -678,6 +730,8 @@ module Harnex
     def details(lane, exit_code)
       name = lane["name"]
       return ["keep waiting: harnex result #{name}"] if exit_code == Waiter::DONE_EXIT_TIMEOUT
+      provider_hint = provider_failure_hint(lane)
+      return ["next: #{provider_hint}"] if lane["kind"] == "ask" && !exit_code.zero? && provider_hint
       return ["more: harnex reply #{name} \"...\""] if lane["kind"] == "ask"
 
       out = []
@@ -697,6 +751,8 @@ module Harnex
         else
           out << "worked in place in #{lane['cwd']}; more work: `harnex reply #{name} \"...\"`"
         end
+      elsif provider_hint
+        out << "next: #{provider_hint}#{lane['branch'] ? "; or `harnex discard #{name}`" : ''}"
       else
         retry_model = model_problem?(lane) ? other_model(lane) : nil
         out << "next: `harnex reply #{name} \"Continue the same task from where you stopped\"" \
@@ -707,6 +763,15 @@ module Harnex
       out
     end
 
+    def provider_failure_hint(lane)
+      case lane["outcome"]
+      when "policy_refusal"
+        "provider refused the content; a retry needs a rephrased brief or another route"
+      when "provider_error_unexplained"
+        "read the provider/gateway logs before retrying; the provider returned no error details"
+      end
+    end
+
     def commit_count(lane)
       count, _err, ok = git(lane["worktree"] || lane["cwd"], "rev-list", "--count", "#{lane['base_sha']}..HEAD")
       ok ? count.to_i : 0

data/lib/harnex/orchestration.rb

@@ -23,7 +23,8 @@ module Harnex
     # are not fatal unless a caller names them (#57). provider_capacity was
     # task_failed before #82 and stays fatal; pass fatal classes to exempt it.
     DEFAULT_FATAL_CLASSES = %w[
-      completed_no_activity task_failed provider_capacity boot_failure permission_prompt timeout process_failed
+      completed_no_activity task_failed provider_capacity policy_refusal provider_error_unexplained
+      boot_failure permission_prompt timeout process_failed
     ].freeze
 
     module_function

data/lib/harnex/runtime/session.rb

@@ -54,7 +54,7 @@ module Harnex
     # rate limits, not the work. Structured signal only, never text.
     OUTCOME_CLASSES = (
       %w[completed_with_proof completed_with_activity] + PROOF_REJECTION_CLASSES +
-      %w[task_failed provider_capacity] + PROCESS_OUTCOME_CLASSES + %w[unknown]
+      %w[task_failed provider_capacity policy_refusal provider_error_unexplained] + PROCESS_OUTCOME_CLASSES + %w[unknown]
     ).freeze
     # Pi tools whose structured results carry an integer exit code.
     PI_COMMAND_TOOLS = %w[bash].freeze
@@ -1263,6 +1263,10 @@ module Harnex
       nil
     end
 
+    # #93: these are Pi's structured errorMessage/finalError, not transcript
+    # text. Explicit provider errors take precedence over exhausted retries.
+    PI_POLICY_REFUSAL = /\bcyber_policy\b|content[\s_-]*(?:filter|policy)|flagged for possible cybersecurity risk/i
+
     def settle_pi_task!
       return if @stop_requested || @pi_transport_failed
 
@@ -1273,8 +1277,16 @@ module Harnex
       when "error", "aborted", "length"
         error = @pi_last_assistant_error || @pi_last_retry_error
         error = "Pi agent settled with stopReason=#{reason}" if error.to_s.empty?
-        capacity = reason == "error" && !@pi_last_retry_error.to_s.empty?
-        mark_task_failed(status: reason, error: error, outcome_class: capacity ? "provider_capacity" : nil)
+        outcome_class = if reason == "error"
+                          if [error, @pi_last_retry_error].any? { |text| text.to_s.match?(PI_POLICY_REFUSAL) }
+                            "policy_refusal"
+                          elsif error == "Unknown error (no error details in response)"
+                            "provider_error_unexplained"
+                          elsif !@pi_last_retry_error.to_s.empty?
+                            "provider_capacity"
+                          end
+                        end
+        mark_task_failed(status: reason, error: error, outcome_class: outcome_class)
       when nil, ""
         mark_task_failed(
           status: "missing_final_message",
@@ -2549,6 +2561,7 @@ module Harnex
       # Status/source derive from the proof verdict, not the refined label.
       proof_failure = %w[
         completed_no_activity report_missing report_invalid report_rejected task_failed provider_capacity
+        policy_refusal provider_error_unexplained
       ].include?(base_class)
       harness_receipt = artifact_payload&.dig("receipt", "author") == "harnex"
       status = receipt_outcome["status"]

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.30.0"
+  VERSION = "0.30.1"
   RELEASE_DATE = "2026-10-25"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.30.1
 platform: ruby
 authors:
 - Jikku Jose
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-28 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,