harnex 0.29.1 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e36a59564be22ba55cda2815e3e72b59b887bb2a4e0417be776295ef1cb10b82
-  data.tar.gz: 0a9b1355a5bc153e4d6fdd6ef79df81f022c5b6a75f97de0a8f91ef52353e526
+  metadata.gz: e3869562568a9927b6a413b5536ee9c489940ce0a8cf9ac6c001072b005ae760
+  data.tar.gz: 1203d0e9e327d56ccb63a119bc27489c417dce551e6be530772b2477e6f592b2
 SHA512:
-  metadata.gz: 1794b1c8190bf40109732a821470d9a24772be9e68e46b9c49732ac46bd24fb73a88d07d0097dece3ec43e3b164932903d69ffda7fa6b4f18b244989990c8a52
-  data.tar.gz: 8163c5eb86dacb6174868459fcc9bba2fb87b66c503e61a96f38baefbe2ca93423df3a84fd07da626927402fe5432f4f541eec202a7b4cc4fde131e1b9ff7de4
+  metadata.gz: 5f445333438f47be5c9f8f8eef6a90c3ce4844d6d4c398ae9f9a1568d4750de3313f741266b325b07d01fb941599473b6b143c827b34aa8608cab47a7f2bd1db
+  data.tar.gz: f5bc3dde8e4ab3b666989418293ce304d53dbcbd4752baf7d17ad1afad86e39af2d8b56bcf28ace274caf5440892ac7111e4fb8dfd02581e9de38757a6659d7e

data/CHANGELOG.md

@@ -1,8 +1,71 @@
 # 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. Published to RubyGems.
+
+### Fixed
+
+- **Lane names collided** (#89). Identical briefs in sibling worktrees of a
+  bare repo all became `pi-read-carry-out-brief`, and `harnex result NAME`
+  then failed with `several lanes are named …`.
+  - A bare layout (`repo/.bare` plus sibling worktrees) is one repo: its main
+    checkout is the worktree on the bare repo's `HEAD` branch, so every
+    worktree shares one lane namespace and `harnex lanes` shows them all.
+  - Generated names skip every name another lane still holds in any repo
+    (working, uncollected, or an unlanded worktree); `--name`, `--worktree`
+    and `ask --id` refuse a name while another repo's worker runs under it;
+    `result`/`reply` find a working lane from anywhere.
+  - A lane working in another worktree is named after it
+    (`pi-night-1024_s3`); brief openers such as "You are a … lane" and "carry
+    out the brief" no longer make the name.
+  - `delegate --worktree` refuses a `--cwd` that is already another worktree
+    of the repo (it would have branched from the main checkout instead).
+- **The `gpt` agent invented a `worktree`** from brief prose (#89). It now
+  sets `worktree`, `name` and `cwd` only from header lines, takes a new
+  `name:` header, and passes `cwd:` on to `result` and `reply`.
+- **A lane in place reported other people's commits** (#91). Its footer
+  counts only commits that appeared while the worker ran a git command, and
+  names the rest: `0 commits (HEAD also moved 6 commits by others)`.
+- **Messages sent straight to a worker were invisible** to the session that
+  started its lane (#92). `harnex send` now records who sent a message, and a
+  lane's result lists messages from anyone but the lane's owner and its own
+  `harnex reply` (`interjected: 1 message … from a terminal (harnex send):
+  "…"`). When a message reached the worker after it had answered, the result
+  shows the answers it replaced first, the original task's report among them.
+
+### Added
+
+- `.harnex/config.json` `lanes` templates put worktree lanes where the repo
+  keeps its worktrees (#90): `{"lanes": {"worktree_path": "../{name}",
+  "branch": "night/{mm}{dd}_{name}"}}` (`{name}`, `{yyyy}`, `{mm}`, `{dd}`).
+  `land` and `discard` follow each lane's own path and branch.
+- MCP `ask` takes `name`.
+
 ## [0.29.1] - 2026-10-23 | 10:31 AM | IST
 
-Local-only fix release for #88: lanes in repos with a phase allowlist.
+Fix release for #88: lanes in repos with a phase allowlist. Published to
+RubyGems on 2026-10-25 | 02:14 AM | IST.
 
 ### 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/agents/gpt.md

@@ -1,6 +1,6 @@
 ---
 name: gpt
-description: "Hand a task or question to a GPT model (a Pi worker run through harnex) and get its reply back verbatim. Use when the user asks for GPT, for another model's opinion or review, or to delegate work to Pi/GPT workers; launch several at once for parallel GPT work, and SendMessage the same agent for follow-ups (the worker keeps its context). While it runs, the harnex `lanes` tool or `harnex lanes` shows what each worker is doing right now (its current tool). Questions and reviews go to a read-only worker; a brief that asks to run commands, tests or benchmarks, or to change files, goes to a worker that can (in the current checkout). The prompt may open with header lines, then a blank line, then the brief: `worktree: NAME` (edit in a new git worktree on branch harnex/NAME; afterwards land it with the harnex `land` tool or `harnex land NAME`, which merges and removes the worktree and branch; don't git merge lane branches by hand), `mode: write` (run commands or edit the current checkout in place), `mode: read` (read-only even if the brief mentions commands), `model: provider/model`, `effort: low|medium|high`, `fallback: provider/model` (read-only asks), `cwd: <dir>`. Write a self-contained brief: the GPT worker has not seen this conversation."
+description: "Hand a task or question to a GPT model (a Pi worker run through harnex) and get its reply back verbatim. Use when the user asks for GPT, for another model's opinion or review, or to delegate work to Pi/GPT workers; launch several at once for parallel GPT work, and SendMessage the same agent for follow-ups (the worker keeps its context). While it runs, the harnex `lanes` tool or `harnex lanes` shows what each worker is doing right now (its current tool). Questions and reviews go to a read-only worker; a brief that asks to run commands, tests or benchmarks, or to change files, goes to a worker that can (in the current checkout). The prompt may open with header lines, then a blank line, then the brief: `worktree: NAME` (edit in a new git worktree on branch harnex/NAME; afterwards land it with the harnex `land` tool or `harnex land NAME`, which merges and removes the worktree and branch; don't git merge lane branches by hand), `mode: write` (run commands or edit the current checkout in place), `mode: read` (read-only even if the brief mentions commands), `model: provider/model`, `effort: low|medium|high`, `fallback: provider/model` (read-only asks), `cwd: <dir>` (work in that directory, e.g. a sibling worktree), `name: NAME` (the lane's name; default: the cwd worktree's name or the brief's first words). Write a self-contained brief: the GPT worker has not seen this conversation."
 tools: mcp__harnex__ask, mcp__harnex__delegate, mcp__harnex__reply, mcp__harnex__result
 mcpServers:
   - harnex
@@ -16,11 +16,16 @@ return its text.
 ## 1. Split the prompt
 
 The prompt may open with header lines `key: value` using only these keys:
-`worktree`, `mode`, `model`, `effort`, `fallback`, `cwd`. The header ends at
-the first line that is not one of them; drop one blank line after it.
+`worktree`, `mode`, `model`, `effort`, `fallback`, `cwd`, `name`. The header
+ends at the first line that is not one of them; drop one blank line after it.
 Everything after the header is the brief, kept exactly as written. No header
 lines means the whole prompt is the brief.
 
+Only header lines set tool arguments. Never take a `worktree`, `name` or
+`cwd` from the brief's wording, even when the brief names a worktree, a
+branch or a directory: the brief goes to the worker as it is, and the worker
+reads it.
+
 ## 2. Call one tool
 
 Pick the tool:
@@ -35,23 +40,26 @@ Then:
 
 - **`delegate`:** call it with
   - `task` = the brief;
-  - `worktree` = NAME, if given;
+  - `worktree` = NAME, only if the header has a `worktree:` line;
+  - `name` = NAME, if the header has a `name:` line and no `worktree:` line;
   - and `model`, `effort`, `cwd` if given.
 - **`ask`:** call it with
   - `question` = the brief;
-  - and `model`, `effort`, `cwd` if given, plus `fallback_model` from
+  - and `model`, `effort`, `cwd`, `name` if given, plus `fallback_model` from
     `fallback:`.
 - **A later message in this conversation** (a follow-up) goes to `reply`, with
   - `name` = the lane named in the last result's `── NAME:` footer;
-  - `message` = the new message, exactly as written.
+  - `message` = the new message, exactly as written;
+  - and `cwd` if the first prompt's header gave one.
 
 Pass every string exactly as written.
 
 ## 3. Still working
 
 If the tool's text ends with a footer saying `still working`, call `result`
-with `names` = [that lane name]. Repeat while it says still working, up to 12
-times. Never start a second lane for the same brief.
+with `names` = [that lane name], and `cwd` if the header gave one. Repeat
+while it says still working, up to 12 times. Never start a second lane for
+the same brief.
 
 ## 4. Return
 

data/docs/agents.md

@@ -59,10 +59,13 @@ Optional header lines, then a blank line, then the brief:
 | `mode: read` | Read-only, even if the brief mentions commands |
 | `model: provider/model`, `effort: low\|medium\|high` | Pick the worker's model |
 | `fallback: provider/model` | Retry a read-only ask on another model |
-| `cwd: DIR` | Work in another directory |
+| `cwd: DIR` | Work in another directory, e.g. a sibling worktree (follow-ups stay there) |
+| `name: NAME` | Name the lane (default: the `cwd` worktree's name, else the brief's first words) |
 
 Without a header, questions and reviews go to a read-only worker, and a brief
-that asks to run something or change files goes to a worker that can.
+that asks to run something or change files goes to a worker that can. Only
+header lines set these: a brief that mentions a worktree or a branch is passed
+on as it is, never turned into a `worktree`.
 The definition ships with harnex as [`agents/gpt.md`](../agents/gpt.md).
 
 ### The CLI from Claude's Bash tool

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

@@ -5,7 +5,8 @@ its follow-ups. You start one with `harnex ask` or `harnex delegate`, collect
 it with `harnex result`, continue it with `harnex reply`, and finish it with
 `harnex land` or `harnex discard`. Every lane has a name, runs in a visible
 tmux window named after it, and leaves a small record so any later command can
-find it by name from anywhere in the repository.
+find it by name from anywhere in the repository (from any worktree of it, a
+bare-repo layout included).
 
 Lanes are the agent-facing layer of harnex. Everything here is also available
 as native tools through [`harnex mcp`](mcp.md), and the low-level `run`, `send`,
@@ -65,10 +66,19 @@ cost, commits and the next commands.
   `harnex/NAME` from `HEAD`. The worker is told to commit there. Parallel lanes
   never collide, and your checkout is untouched until you land. If your checkout
   has uncommitted changes, harnex warns that the worktree starts from `HEAD`.
-- **Without `--worktree`** the worker works in the current directory, which is
-  right for tasks that only run or inspect things (tests, a benchmark, a long
-  command). `--name NAME` names the lane; otherwise harnex derives a name from
-  the task (`pi-slow-bench`).
+  A repo that keeps its worktrees elsewhere says so in `.harnex/config.json`
+  (see [Where things live](#where-things-live)).
+- **Without `--worktree`** the worker works in the current directory, or in
+  `--cwd DIR`, which is right for tasks that only run or inspect things (tests,
+  a benchmark, a long command) and for a worktree you made yourself.
+- **Names.** `--name NAME` names the lane. Otherwise a lane working in another
+  worktree of the repo is named after it (`--cwd ../night-1024_s3` gives
+  `pi-night-1024_s3`), and any other lane after the task's first words
+  (`pi-slow-bench`, then `pi-slow-bench-2`). Generated names skip every name
+  another lane still holds anywhere (working, uncollected, or a worktree not
+  yet landed), and a name you choose is refused while another repo's worker
+  is running under it, so `harnex result NAME` and `reply NAME` find a
+  working lane from anywhere.
 - **`--file PATH`** reads a long brief from a file. Briefs must be
   self-contained: the worker has not seen your conversation. Name the files, the
   expected behavior and how to verify it.
@@ -126,6 +136,11 @@ or bare `land`.
 `harnex discard NAME` stops the lane if it is still working and deletes its
 worktree and branch without merging.
 
+**Lanes in place.** For a lane without a worktree, the footer counts only the
+commits the worker made (harnex watches `HEAD` around each git command the
+worker runs). Commits someone else made in the same checkout meanwhile are
+named apart: `0 commits (HEAD also moved 3 commits by others)`.
+
 ## Parallel lanes
 
 ```bash
@@ -153,6 +168,26 @@ mid-task as a follow-up; a lane that has finished is relaunched on its own Pi
 session (`pi --session`), so it remembers everything from the earlier turns.
 The footer's cost is the lane's total so far.
 
+**Messages from someone else.** Anyone can `harnex send` to a lane's worker
+(the owner from another terminal, a buddy). The lane's result then says so,
+so the session that started the lane is not left guessing:
+
+```text
+[earlier reply this turn, before another message reached the worker]
+Review: PASS (0 P1, 2 P2) ...
+
+[latest reply]
+Understood; the report is now in /tmp/review.md.
+
+── review: done in 6m10s · gpt-6.1-sol · $0.41 · 0 commits
+   interjected: 1 message reached the worker from outside this lane (the reply above may answer it; all: `harnex events --id review`):
+     23:26:04 from a terminal (harnex send): "Write the report to /tmp/review.md instead"
+```
+
+The worker's earlier answers in the same turn (the original task's report
+among them) come first; your own `harnex reply` follow-ups are never listed as
+interjections.
+
 ## When a model fails
 
 ```text
@@ -164,7 +199,14 @@ The footer's cost is the lane's total so far.
 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
 
@@ -179,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
@@ -188,7 +235,18 @@ worker's tmux window, and the window itself is always there to watch.
   repo, worktree, branch, model, owner, Pi session, cost, last result). Closed
   lanes are pruned after 30 days; open lanes never are.
 - **Worktrees:** `.harnex/worktrees/NAME` inside your repository, on branch
-  `harnex/NAME`.
+  `harnex/NAME`. To keep them beside the main checkout instead, set templates
+  in the repo's `.harnex/config.json` (`{name}`, `{yyyy}`, `{mm}`, `{dd}`;
+  the path is relative to the main checkout). `land` and `discard` follow the
+  lane's own path and branch:
+
+  ```json
+  { "lanes": { "worktree_path": "../night-{mm}{dd}_{name}", "branch": "night/{mm}{dd}_{name}" } }
+  ```
+
+- **Bare-repo layouts** (`repo/.bare` plus sibling worktrees): the main
+  checkout is the worktree on the bare repo's `HEAD` branch (`master`), and
+  every worktree of the repo shares its lanes.
 - **`.harnex/`** is added to the clone's `.git/info/exclude` the first time
   harnex writes there, so lane worktrees and dispatch rows never show up as
   untracked work. Nothing tracked changes.

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

@@ -112,6 +112,9 @@ module Harnex
 
     def register_lane(id, model)
       cwd = File.expand_path(@options[:cwd] || Dir.pwd)
+      if (other = Lanes.live_holder(id))
+        raise OptionParser::InvalidArgument, "a worker named #{id} is working in #{other['repo_root']}; pick another --id"
+      end
       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,
@@ -204,7 +207,8 @@ module Harnex
       answer = full_answer(turn)
       case exit_code
       when 0
-        @out.puts answer.to_s
+        lane = answered_lane(result["id"])
+        @out.puts(lane ? Lanes.render_answer(lane, turn.merge("final_message" => answer.to_s, "final_message_truncated" => false)) : 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'])}")
@@ -212,10 +216,18 @@ 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
 
+    def answered_lane(id)
+      id && Lanes.resolve(id, from: File.expand_path(@options[:cwd] || Dir.pwd))
+    rescue OptionParser::InvalidArgument
+      nil
+    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)

data/lib/harnex/commands/delegate.rb

@@ -17,8 +17,12 @@ module Harnex
         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)
+                           `harnex discard NAME`. The repo's .harnex/config.json
+                           can move it: {"lanes": {"worktree_path": "../{name}",
+                           "branch": "night/{mm}{dd}_{name}"}}
+          --name NAME      Lane name without a worktree (default: the --cwd
+                           worktree's name, else from the task). A working
+                           lane's name is unique across every repo
           --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
@@ -86,9 +90,10 @@ module Harnex
       root = Lanes.main_root(workdir)
       raise OptionParser::InvalidArgument, "--worktree needs a git repository (#{workdir} is not in one)" if @options[:worktree] && root.nil?
 
+      refuse_nested_worktree!(root, workdir) if @options[:worktree]
       Lanes.sweep_merged(root)
       root ||= workdir
-      name = Lanes.validate_name!(@options[:worktree] || @options[:name] || Lanes.generate_name(root, task))
+      name = Lanes.validate_name!(@options[:worktree] || @options[:name] || Lanes.generate_name(root, task, cwd: workdir))
       ensure_free!(root, name)
       lane = {
         "name" => name, "kind" => "delegate", "repo_root" => root, "run_root" => root, "cwd" => workdir,
@@ -125,11 +130,27 @@ module Harnex
               "lane #{name} already exists (#{existing['state']}): follow up with `harnex reply #{name} \"...\"`, " \
               "or `harnex land #{name}` / `harnex discard #{name}` first"
       end
+      if (other = Lanes.live_holder(name)) && other["repo_root"] != root
+        raise OptionParser::InvalidArgument,
+              "a worker named #{name} is working in #{other['repo_root']}; working lanes' names are unique, " \
+              "so pick another name (or wait: `harnex result #{name}`)"
+      end
       return unless Harnex.read_registry(root, name)
 
       raise OptionParser::InvalidArgument, "a harnex session named #{name} is running; pick another name"
     end
 
+    # #89: --cwd in a sibling worktree plus --worktree would branch a new
+    # worktree from the main checkout, not from --cwd; say so instead.
+    def refuse_nested_worktree!(root, workdir)
+      top = Lanes.toplevel(workdir)
+      return if top.nil? || root.nil? || Lanes.same_dir?(top, root)
+
+      raise OptionParser::InvalidArgument,
+            "--cwd #{top} is already a worktree of #{root}: drop --worktree to work there in place, " \
+            "or drop --cwd to start a new worktree from the main checkout"
+    end
+
     def warn_uncommitted(root)
       dirty = Lanes.dirty_paths(root)
       return if dirty.empty?

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/commands/reply.rb

@@ -61,7 +61,8 @@ module Harnex
     def follow_up(lane, message)
       argv = @harnex_command + ["send", "--id", lane["name"], "--repo", lane["run_root"], "--message", message]
       argv += ["--wait-done"] + (@options[:timeout] ? ["--timeout", @options[:timeout].to_s] : []) if @options[:wait]
-      stdout, stderr, status = Open3.capture3(*argv)
+      # Marked as the lane's own follow-up, not an interjection (#92).
+      stdout, stderr, status = Open3.capture3({ "HARNEX_SEND_VIA" => "reply" }, *argv)
       result = Lanes.last_json(stdout)
       raise Lanes::LaunchError, "harnex could not reach lane #{lane['name']}: #{stderr.strip.lines.last}" if result.empty?
 

data/lib/harnex/commands/result.rb

@@ -71,7 +71,7 @@ module Harnex
       text = if @options[:json]
                JSON.generate(lane: lane["name"], exit_code: exit_code, state: lane["state"], result: turn)
              elsif lane["kind"] == "ask" && exit_code.zero?
-               Lanes.final_message(turn)
+               Lanes.render_answer(lane, turn)
              else
                Lanes.render(lane, turn, exit_code)
              end

data/lib/harnex/commands/send.rb

@@ -141,7 +141,8 @@ module Harnex
           text: text,
           submit: @options[:submit],
           enter_only: @options[:submit_only],
-          force: @options[:force]
+          force: @options[:force],
+          from: Harnex.sender_identity
         )
 
         Net::HTTP.start(

data/lib/harnex/commands/wait.rb

@@ -488,7 +488,8 @@ module Harnex
       }
       payload[:turn] = event["turn"] if event["turn"]
       payload[:follow_ups] = event["follow_ups"] if event["follow_ups"]
-      %w[end_sha commits turn_commits model final_message final_message_path final_message_truncated].each do |key|
+      %w[end_sha commits turn_commits model final_message final_message_path final_message_truncated
+         earlier_replies].each do |key|
         payload[key.to_sym] = event[key] if event.key?(key)
       end
       exit_code = 0