harnex 0.7.7 → 0.7.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09276571f581a98eb6c613e88e4035ed8420bcae710c43d57e307cc5eb4d468b'
-  data.tar.gz: 886e1555b2ee4d128d992e4d35aafc716c0bc2aa16318123b053e5e128a7337a
+  metadata.gz: 56d9111b2ab4f12716444ecef721331d9878a4485a4b305ecd4a1ad7546d4b77
+  data.tar.gz: 3f727b473455245ba916cabe1202a6abc2d6c5a07f4ae257b04898a296d9149c
 SHA512:
-  metadata.gz: 90f7f457f829f99424c1f2635706c3231c08bf1cea7329e47b6992fde3aa45e123c40c0d278bf2c9a5c8bc2ecd6d0f742a812320c659c5bbe68fd4ab94df6c9d
-  data.tar.gz: 65323fa96b6f5c92564b2be10cfe802f846fff1b76079f26cbaa362588dce50ae86a59c250b456058f3acad8ca31f03c9c49b2ad096c85a6aae5510797ff3abb
+  metadata.gz: a2a87ae57e9ddc34bb85805ea9e07f3523691cf979361f687f4c3c68534c0b9f7c9e276b83d8d28a91a15bc52913ef41e1e36b1993127c97c68c87aa75af5766
+  data.tar.gz: 92084ab180df22e16316226adaaa8170b0ab71ceeda1e4de3f097873ed6ecb8e22f8bca7b06b3c78b0a1a0c36d8b18c4b13dcebb7126aecd4523034fead38399

data/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## [Unreleased]
 
+## [0.7.9] - 2026-07-10 | 10:33 PM | IST
+
+### Added
+
+- `harnex run` now accepts wrapper-level `--cwd DIR` and `--root DIR` options.
+  `--cwd` starts the wrapped agent in `DIR` and makes that directory the
+  harnex session root for registry/session metadata and default dispatch
+  summaries. `--root` changes harnex root attribution without changing the
+  child process cwd.
+
+### Changed
+
+- `harnex run --help`, README, and the dispatch guide now document
+  public-bundle / temporary-workdir dispatches with `--cwd`.
+- Refreshed pinned Codex app-server schema fixtures against
+  `codex-cli 0.144.1` so the release suite is green with the current local
+  Codex CLI.
+
+### Fixed
+
+- Non-git temporary work directories no longer leak raw `git rev-parse` fatal
+  messages during harnex root probing.
+
+## [0.7.8] - 2026-06-13 | 08:45 PM | IST
+
+### Added
+
+- `harnex watch --id <id> --until done` now provides a native work-terminal
+  watcher for existing visible/detached sessions. It exits `0` for successful
+  work, non-zero for `task_failed` / failed terminal telemetry, `124` for
+  wall-clock timeout, and can write optional done/fail marker files for legacy
+  queue integrations.
+
+### Changed
+
+- Monitoring docs now recommend native `harnex watch` for unattended
+  single-dispatch monitoring and reserve `harnex run --watch` for foreground
+  launch-and-stall-recovery.
+
 ## [0.7.7] - 2026-06-12 | 10:48 AM | IST
 
 ### Fixed

data/README.md

@@ -57,6 +57,24 @@ harnex stop --id planner
 That's the core loop. Start a fresh agent for each step, hand it one
 job, watch it work, stop it when done.
 
+### Run from a temporary/public bundle
+
+Use `--cwd DIR` when the worker should see a specific directory rather than
+the orchestrator's current repo. Harnex starts the wrapped agent in `DIR`, sets
+that directory as the session root, and resolves default telemetry such as
+`.harnex/dispatch.jsonl` there:
+
+```bash
+harnex run codex --cwd /tmp/leximaze_eval_run_001 \
+  --id lm-run-001 \
+  --context "Read README.md and write RESPONSES.jsonl and OUTPUT.md" \
+  --auto-stop
+```
+
+Use `--root DIR` only when you need to override harnex's root attribution
+without changing the child process cwd. `--cwd` is not a security sandbox; it is
+an explicit working-directory/root selector for automation.
+
 ## Why use this
 
 - **You want agents to plan, implement, review, and fix — in sequence.**
@@ -68,8 +86,9 @@ job, watch it work, stop it when done.
   `harnex events` streams structured JSONL lifecycle events.
 
 - **You don't want to babysit.** Use `--context --auto-stop` for
-  one-shot work, `--watch` for bounded stall recovery, or
-  `--wait-for-idle` as a send fence.
+  one-shot work, `harnex watch` for existing visible/detached dispatches,
+  `run --watch` for bounded foreground stall recovery, or `--wait-for-idle`
+  as a send fence.
 
 - **You want local-only orchestration.** Everything runs on your
   machine. No cloud services, no API keys beyond what the agents need.
@@ -150,18 +169,27 @@ harnex agents-guide monitoring
 
 ## Built-in dispatch monitoring
 
-For unattended dispatches, use `--watch` instead of writing a bash poll loop:
+For unattended visible/background dispatches, use `harnex watch` instead of
+writing a bash poll loop around `harnex wait`:
 
 ```bash
-harnex run pi --id pi-impl-42 --watch --preset impl \
+harnex run pi --id pi-impl-42 --tmux pi-impl-42 \
   --context "Implement koder/plans/42_plan.md. Run tests and commit when done."
+harnex watch --id pi-impl-42 --until done --max-wait 90m \
+  --done-marker /tmp/pi-impl-42-done.json \
+  --fail-marker /tmp/pi-impl-42-failed.json
 ```
 
-`--watch` runs a foreground babysitter that checks session activity every 60s,
-force-resumes on stall up to a cap, and exits when the target session exits or
-the resume cap is reached. It is foreground-only; use `--tmux` or `--detach`
-for visible/background sessions, and `--watch` when the current command should
-block as the monitor.
+`harnex watch --until done` is the safe work-terminal watcher for existing
+`--tmux` or detached sessions. It exits `0` for `task_complete`/done, non-zero
+for `task_failed` or failed terminal summaries, and `124` for `--max-wait`
+timeouts. It does not keep pane/status polling after a terminal failure signal.
+
+`harnex run --watch` is a separate foreground babysitter that checks session
+activity every 60s, force-resumes on stall up to a cap, and exits when the
+target session exits or the resume cap is reached. It is foreground-only; use
+`--tmux` or `--detach` for visible/background sessions, and `run --watch` when
+the current command should launch and monitor one worker.
 
 Presets map to stall policy defaults:
 
@@ -180,11 +208,15 @@ and stops the session after the first task completion or PTY prompt return.
 
 ## Completion and waiting
 
-Choose the wait predicate that matches how you launched the worker:
+Choose the wait/watch predicate that matches how you launched the worker:
 
-- `harnex wait --id ID --until done --timeout SECS` is the safest unattended
-  work fence. It returns when Harnex sees `task_complete`, `task_failed`, or a
-  terminal exit, whichever comes first; failed work returns non-zero.
+- `harnex watch --id ID --until done --max-wait DUR` is the safest unattended
+  monitor for an existing visible or detached dispatch. It wraps the work-level
+  fence, preserves the timeout/failure distinction, and can write done/fail
+  marker files for legacy queue integrations.
+- `harnex wait --id ID --until done --timeout SECS` is the primitive work fence.
+  It returns when Harnex sees `task_complete`, `task_failed`, or a terminal
+  exit, whichever comes first; failed work returns non-zero.
 - `harnex wait --id ID` waits for the wrapped process to exit. This is right
   for already-exited sessions and terminal-summary recovery, but interactive
   agents can stay open after finishing a turn.
@@ -214,9 +246,11 @@ Schema details and compatibility policy are documented in
 
 ## Dispatch history
 
-Every finished `harnex run` writes dispatch records. In a git repo, the
-default path is `<repo>/.harnex/dispatch.jsonl`; outside a git repo, the
-compact history record falls back to `~/.local/state/harnex/dispatch.jsonl`.
+Every finished `harnex run` writes dispatch records. By default, the terminal
+summary JSONL path is `<session-root>/.harnex/dispatch.jsonl`; `--cwd DIR` makes
+`DIR` the session root, including for non-git temporary bundles. The compact
+history record is repo-local in a git tree and falls back to
+`~/.local/state/harnex/dispatch.jsonl` outside git.
 `harnex history` reads the compact records from that location, and
 `harnex status --id ID --json` / `harnex wait` can use the same durable
 terminal summaries when the live session registry is already gone.
@@ -313,6 +347,7 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until the turn returns idle) |
 | `harnex stop --id <id>` | Send the agent's native exit sequence |
 | `harnex status` | List running sessions; with `--id ID --json`, terminal summaries can classify completed/failed sessions after exit |
+| `harnex watch --id <id>` | Safely monitor existing visible/detached work until `done`, `task_failed`, or timeout; optional done/fail markers |
 | `harnex pane --id <id>` | Capture a tmux-backed session's screen (`--follow` for live) |
 | `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
 | `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |

data/guides/01_dispatch.md

@@ -73,7 +73,7 @@ for i in 1 2 3; do
   harnex run pi --id w-$i --tmux w-$i --detach \
     --context "Read and execute /tmp/task-$i.md" --auto-stop &
 done
-for i in 1 2 3; do harnex wait --id w-$i --until done & done
+for i in 1 2 3; do harnex watch --id w-$i --until done --max-wait 90m & done
 wait
 ```
 
@@ -81,6 +81,20 @@ Rule: when you use `--tmux`, pass the same name as `--id`. If you pass only
 `--tmux NAME`, harnex creates a random session ID and the pane name no longer
 matches `harnex status` or `harnex pane --id`.
 
+For public-bundle or benchmark runs, use `--cwd DIR` to make harnex launch the
+wrapped agent from that directory and associate session metadata/default
+telemetry with it:
+
+```bash
+harnex run codex --cwd /tmp/leximaze_eval_run_001 \
+  --id lm-run-001 \
+  --context "Read README.md and write RESPONSES.jsonl and OUTPUT.md" \
+  --auto-stop
+```
+
+`--root DIR` only overrides harnex's root attribution; it does not change the
+child process cwd. Neither flag is a sandbox.
+
 Pi runs use structured RPC (`pi --mode rpc`). Pass Pi child flags after `--`
 (e.g. `harnex run pi --context "..." -- --model anthropic/claude-sonnet-4-5 --thinking high`).
 
@@ -125,18 +139,24 @@ Use the lightest primitive that gives the signal you need:
 | Continuous pane view | `harnex pane --id pi-i-NN --follow` |
 | Transcript tail | `harnex logs --id pi-i-NN --lines 80` |
 | Structured events | `harnex events --id pi-i-NN --snapshot` |
-| Work completion/failure fence | `harnex wait --id pi-i-NN --until done` |
+| Existing-session work monitor | `harnex watch --id pi-i-NN --until done --max-wait 90m` |
+| Primitive work completion/failure fence | `harnex wait --id pi-i-NN --until done` |
 | Native successful-turn completion | `harnex wait --id pi-i-NN --until task_complete` |
 
-For unattended policy-only stall recovery, use built-in watch mode:
+For visible `--tmux` or detached dispatches, prefer `harnex watch --id`: it
+returns `0` on done, non-zero on `task_failed`/failed terminal summaries, and
+`124` on `--max-wait` timeout. Use `--done-marker` / `--fail-marker` only as
+compatibility outputs for older queue scripts.
+
+For foreground launch-and-stall-recovery, use `harnex run --watch`:
 
 ```bash
 harnex run pi --id pi-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
 ```
 
-`--watch` is foreground-blocking. Use it when a single process should launch
-and monitor the worker. Use pane/log/event polling or a buddy when you need
-interpretation, multiple sessions, or a separate watcher.
+`run --watch` is foreground-blocking. Use it when a single process should
+launch and monitor the worker. Use pane/log/event polling or a buddy when you
+need interpretation across multiple sessions.
 
 ## Verify And Stop
 

data/guides/03_buddy.md

@@ -4,7 +4,14 @@ A buddy is a second harnex session that watches one or more workers and nudges
 them if they stall. Use a buddy when the work is long-running, unattended, or
 needs interpretation that simple stall policy cannot provide.
 
-For simple inactivity recovery, prefer built-in watch mode:
+For simple work-terminal monitoring of an existing visible/detached session,
+prefer the native watcher:
+
+```bash
+harnex watch --id pi-i-NN --until done --max-wait 90m
+```
+
+For foreground launch-and-inactivity recovery, use built-in run watch mode:
 
 ```bash
 harnex run pi --id pi-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"

data/guides/04_monitoring.md

@@ -17,12 +17,15 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For unattended monitors, prefer `harnex wait --until done`: it returns on the
-work-level `task_complete` or `task_failed` signal, or terminal exit, whichever
-comes first. Failed work returns non-zero. For structured sessions (Pi RPC and
-Codex app-server), `harnex wait --until task_complete` remains the exact
-successful-turn fence. Neither knows your acceptance criteria; verify the
-expected artifact or tests afterward.
+For unattended monitors on existing visible/detached sessions, prefer
+`harnex watch --until done`: it returns on the work-level `task_complete` or
+`task_failed` signal, or terminal exit, whichever comes first. Successful work
+exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
+callers that need the lower-level primitive, `harnex wait --until done` exposes
+the same work fence. For structured sessions (Pi RPC and Codex app-server),
+`harnex wait --until task_complete` remains the exact successful-turn fence.
+None of these know your acceptance criteria; verify the expected artifact or
+tests afterward.
 
 ## Completion Test
 
@@ -30,15 +33,19 @@ For unattended work, first gate on harnex work completion, then verify the task
 artifact and repo health:
 
 ```bash
-harnex wait --id pi-i-NN --until done --timeout 5400 &&
+harnex watch --id pi-i-NN --until done --max-wait 90m \
+  --done-marker /tmp/pi-i-NN-done.json \
+  --fail-marker /tmp/pi-i-NN-failed.json &&
   test -f path/to/expected-artifact &&
   test -z "$(git status --short)"
 ```
 
-`harnex wait --until done` succeeds from `task_complete` or durable successful
-terminal telemetry (`--summary-out` / `.harnex/dispatch.jsonl` / exit status),
-returns non-zero for `task_failed` / failed terminal telemetry, and does not use
-tmp done markers.
+`harnex watch --until done` wraps the `harnex wait --until done` work fence:
+it succeeds from `task_complete` or durable successful terminal telemetry
+(`--summary-out` / `.harnex/dispatch.jsonl` / exit status), returns non-zero for
+`task_failed` / failed terminal telemetry, returns `124` for `--max-wait`, and
+only writes done/fail markers as compatibility outputs after harnex has seen a
+terminal work signal.
 
 Adjust the artifact path to the task. The point is to avoid declaring done while
 a worker is between edits or between commits.
@@ -76,42 +83,29 @@ harnex events --id pi-i-NN
 For task completion:
 
 ```bash
+harnex watch --id pi-i-NN --until done --max-wait 15m
+# Primitive equivalent when a script wants raw wait semantics:
 harnex wait --id pi-i-NN --until done --timeout 900
-# Or, when you specifically need the structured turn event:
+# Or, when you specifically need the structured successful-turn event:
 harnex wait --id pi-i-NN --until task_complete --timeout 900
 ```
 
 ## Background Sweeper
 
-Consumers often run a small shell loop that checks terminal state, then drops
-to pane diagnostics only while work is still running. Keep a hard wall-clock cap
-so an unattended pipeline cannot wait forever:
+Avoid custom shell loops that repeatedly call `harnex wait`/`harnex status` and
+then accidentally swallow a failed work result. For a single unattended
+visible/detached dispatch, use the native watcher with a hard wall-clock cap:
 
 ```bash
-start=$(date +%s)
-max_wait=5400
-
-while :; do
-  if test "$(($(date +%s) - start))" -gt "$max_wait"; then
-    echo "wall-clock cap hit for pi-i-NN" >&2
-    exit 2
-  fi
-
-  row=$(harnex status --id pi-i-NN --json | ruby -rjson -e 'rows=JSON.parse(STDIN.read); print JSON.generate(rows.first || {})')
-  done=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["done"] ? "true" : "false")')
-  work_state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["work_state"].to_s)')
-  state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["state"].to_s)')
-
-  case "$done:$work_state" in
-    true:*) echo "pi-i-NN work completed"; break ;;
-    false:failed) echo "pi-i-NN work failed; process state: $state" >&2; exit 1 ;;
-    *) harnex pane --id pi-i-NN --lines 20 ;;
-  esac
-
-  sleep 60
-done
+harnex watch --id pi-i-NN --until done --max-wait 90m \
+  --done-marker /tmp/pi-i-NN-done.json \
+  --fail-marker /tmp/pi-i-NN-failed.json
 ```
 
+If that exits `124`, inspect the pane/logs/events and decide whether to nudge,
+stop, or continue. If it exits any other non-zero code, treat the work as
+failed; do not continue polling the same task as though it were still running.
+
 Recommended caps:
 
 | Work type | Cap |
@@ -120,17 +114,18 @@ Recommended caps:
 | Medium implementation | 90 minutes |
 | Large unattended phase | 3 hours |
 
-## Built-In Watch Mode
+## Built-In Stall Babysitter
 
 Use `harnex run --watch` when one foreground process should launch the worker
-and apply bounded stall recovery:
+and apply bounded stall recovery. This is different from `harnex watch --id`,
+which watches an existing session's work-terminal state:
 
 ```bash
 harnex run pi --id pi-i-NN --watch --preset impl \
   --context "Read /tmp/task-impl-NN.md"
 ```
 
-`--watch` exits with:
+`run --watch` exits with:
 
 | Code | Meaning |
 | --- | --- |
@@ -145,6 +140,7 @@ interpretation.
 
 - Polling `state=completed` alone and missing live sessions with `task_complete=true`.
 - Polling `state=prompt` alone and calling it done.
+- Wrapping `harnex wait` in loops that swallow non-zero `task_failed` results.
 - Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
 - Letting an unattended loop run with no wall-clock cap.
 - Reading raw tmux panes instead of `harnex pane`.

data/lib/harnex/cli.rb

@@ -15,6 +15,8 @@ module Harnex
         Sender.new(@argv.drop(1)).run
       when "wait"
         Waiter.new(@argv.drop(1)).run
+      when "watch"
+        WatchCommand.new(@argv.drop(1)).run
       when "stop"
         Stopper.new(@argv.drop(1)).run
       when "status"
@@ -59,6 +61,8 @@ module Harnex
         Sender.usage
       when "wait"
         Waiter.usage
+      when "watch"
+        WatchCommand.usage
       when "stop"
         Stopper.usage
       when "status"
@@ -90,6 +94,7 @@ module Harnex
           harnex run <cli> [options] [--] [cli-args...]
           harnex send --id ID [options] [text...]
           harnex wait --id ID [options]
+          harnex watch --id ID [options]
           harnex stop --id ID [options]
           harnex status [options]
           harnex logs --id ID [options]
@@ -104,6 +109,7 @@ module Harnex
           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
@@ -129,6 +135,7 @@ module Harnex
           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

data/lib/harnex/commands/run.rb

@@ -8,11 +8,11 @@ module Harnex
     KNOWN_FLAGS = %w[
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
-      --timeout --inbox-ttl --auto-stop --fast --legacy-pty --help
+      --cwd --root --timeout --inbox-ttl --auto-stop --fast --legacy-pty --help
     ].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
-      --max-resumes --preset --context --meta --summary-out --timeout --inbox-ttl
+      --max-resumes --preset --context --meta --summary-out --cwd --root --timeout --inbox-ttl
     ].freeze
 
     def self.usage(program_name = "harnex run")
@@ -37,6 +37,8 @@ module Harnex
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
           --summary-out PATH Append dispatch telemetry summary JSONL to PATH
+          --cwd DIR          Run the wrapped agent from DIR and use DIR as the session root
+          --root DIR         Override harnex session/root attribution without changing child cwd
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
           --inbox-ttl SECS   Expire queued inbox messages after SECS (default: #{Inbox::DEFAULT_TTL})
           --legacy-pty       (codex only) Use the legacy PTY adapter instead of
@@ -58,6 +60,7 @@ module Harnex
           #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md"
           #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md" --auto-stop
           #{program_name} pi --id pi-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
+          #{program_name} codex --cwd /tmp/public-bundle --id eval-001 --context "Read README.md and write OUTPUT.md" --auto-stop
           #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
 
         Gotchas:
@@ -88,6 +91,8 @@ module Harnex
         context: nil,
         meta: nil,
         summary_out: nil,
+        cwd: nil,
+        root: nil,
         auto_stop: false,
         detach: false,
         tmux: false,
@@ -110,7 +115,7 @@ module Harnex
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
       validate_auto_stop_context!
 
-      repo_root = Harnex.resolve_repo_root(adapter_repo_path(cli_name, child_args))
+      repo_root = resolve_run_root(cli_name, child_args)
       @options[:summary_out] = resolve_summary_out(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
@@ -173,6 +178,8 @@ module Harnex
       tmux_cmd << "--auto-stop" if @options[:auto_stop]
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
+      tmux_cmd += ["--cwd", @options[:cwd]] if @options[:cwd]
+      tmux_cmd += ["--root", @options[:root]] if @options[:root]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
       tmux_cmd << "--fast" if @options[:fast]
       tmux_cmd += ["--legacy-pty"] if @options[:legacy_pty]
@@ -181,11 +188,12 @@ module Harnex
       window_name = @options[:tmux_name] || @options[:id]
       shell_cmd = tmux_cmd.map { |arg| Shellwords.shellescape(arg) }.join(" ")
 
+      tmux_start_cwd = @options[:cwd] || @launch_cwd
       started =
         if ENV["TMUX"]
-          system("tmux", "new-window", "-c", @launch_cwd, "-n", window_name, "-d", shell_cmd)
+          system("tmux", "new-window", "-c", tmux_start_cwd, "-n", window_name, "-d", shell_cmd)
         else
-          system("tmux", "new-session", "-c", @launch_cwd, "-d", "-s", "harnex", "-n", window_name, shell_cmd)
+          system("tmux", "new-session", "-c", tmux_start_cwd, "-d", "-s", "harnex", "-n", window_name, shell_cmd)
         end
 
       raise "tmux failed to start #{cli_name.inspect}" unless started
@@ -281,7 +289,8 @@ module Harnex
         summary_out: @options[:summary_out],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
-        launch_cwd: @launch_cwd
+        launch_cwd: history_cwd,
+        child_cwd: session_child_cwd
       )
     end
 
@@ -289,6 +298,24 @@ module Harnex
       Harnex.build_adapter(cli_name, child_args, legacy_pty: @options[:legacy_pty]).infer_repo_path(child_args)
     end
 
+    def resolve_run_root(cli_name, child_args)
+      return @options[:root] if @options[:root]
+      return @options[:cwd] if @options[:cwd]
+
+      Harnex.resolve_repo_root(adapter_repo_path(cli_name, child_args))
+    end
+
+    def history_cwd
+      @options[:root] || @options[:cwd] || @launch_cwd
+    end
+
+    def session_child_cwd
+      return @options[:cwd] if @options[:cwd]
+      return @launch_cwd if @options[:root]
+
+      nil
+    end
+
     def apply_context(child_args)
       return child_args unless @options[:context]
 
@@ -441,6 +468,16 @@ module Harnex
           @options[:summary_out] = required_option_value(arg, argv[index])
         when /\A--summary-out=(.+)\z/
           @options[:summary_out] = required_option_value("--summary-out", Regexp.last_match(1))
+        when "--cwd"
+          index += 1
+          @options[:cwd] = expand_existing_directory(required_option_value(arg, argv[index]), option_name: arg)
+        when /\A--cwd=(.+)\z/
+          @options[:cwd] = expand_existing_directory(required_option_value("--cwd", Regexp.last_match(1)), option_name: "--cwd")
+        when "--root"
+          index += 1
+          @options[:root] = expand_existing_directory(required_option_value(arg, argv[index]), option_name: arg)
+        when /\A--root=(.+)\z/
+          @options[:root] = expand_existing_directory(required_option_value("--root", Regexp.last_match(1)), option_name: "--root")
         when "--timeout"
           index += 1
           @options[:timeout] = Float(required_option_value(arg, argv[index]))
@@ -509,7 +546,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|cwd|root|timeout|inbox-ttl)=/
           nil
         when /\A--preset=/
           nil
@@ -528,7 +565,7 @@ module Harnex
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
           "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
-          "--timeout=", "--inbox-ttl="
+          "--cwd=", "--root=", "--timeout=", "--inbox-ttl="
         )
     end
 
@@ -585,6 +622,13 @@ module Harnex
       raise OptionParser::InvalidArgument, "#{option_name} must be an integer"
     end
 
+    def expand_existing_directory(value, option_name:)
+      path = File.expand_path(value.to_s, @launch_cwd)
+      return path if File.directory?(path)
+
+      raise OptionParser::InvalidArgument, "#{option_name} must be an existing directory: #{value}"
+    end
+
     def parse_meta(value)
       parsed = JSON.parse(value)
       return parsed if parsed.is_a?(Hash)

data/lib/harnex/commands/watch.rb

@@ -1,5 +1,8 @@
+require "fileutils"
 require "json"
 require "net/http"
+require "optparse"
+require "stringio"
 require "uri"
 
 module Harnex
@@ -206,4 +209,205 @@ module Harnex
       @monotonic_clock.call
     end
   end
+
+  class TerminalWatcher
+    TIMEOUT_EXIT_CODE = 124
+
+    def initialize(
+      id:,
+      repo_path: Dir.pwd,
+      until_state: "done",
+      max_wait: nil,
+      done_marker: nil,
+      fail_marker: nil,
+      stop_on_terminal: false,
+      out: $stdout,
+      err: $stderr
+    )
+      @id = Harnex.normalize_id(id)
+      @repo_path = repo_path
+      @until_state = until_state.to_s.strip.empty? ? "done" : until_state.to_s
+      @max_wait = max_wait
+      @done_marker = done_marker
+      @fail_marker = fail_marker
+      @stop_on_terminal = stop_on_terminal
+      @out = out
+      @err = err
+    end
+
+    def run
+      raise "harnex watch: only --until done is supported" unless @until_state == "done"
+
+      output, warnings, exit_code = capture_wait
+      @err.write(warnings) unless warnings.empty?
+      @out.write(output) unless output.empty?
+
+      payload = parse_payload(output)
+      outcome = classify(exit_code, payload)
+      case outcome
+      when :success
+        write_marker(@done_marker, payload, outcome: outcome, exit_code: exit_code)
+      when :failed
+        write_marker(@fail_marker, payload, outcome: outcome, exit_code: exit_code)
+      end
+
+      stop_session if @stop_on_terminal && outcome != :timeout
+      exit_code
+    end
+
+    private
+
+    def capture_wait
+      argv = ["--id", @id, "--repo", @repo_path, "--until", @until_state]
+      argv += ["--timeout", @max_wait.to_s] if @max_wait
+
+      out_buffer = StringIO.new
+      err_buffer = StringIO.new
+      original_stdout = $stdout
+      original_stderr = $stderr
+      $stdout = out_buffer
+      $stderr = err_buffer
+      exit_code = Waiter.new(argv).run
+      [out_buffer.string, err_buffer.string, exit_code]
+    ensure
+      $stdout = original_stdout
+      $stderr = original_stderr
+    end
+
+    def parse_payload(output)
+      line = output.to_s.lines.reverse.find { |candidate| !candidate.strip.empty? }
+      return {} unless line
+
+      parsed = JSON.parse(line)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def classify(exit_code, payload)
+      return :timeout if exit_code == TIMEOUT_EXIT_CODE || payload["status"].to_s == "timeout"
+      return :success if exit_code.to_i.zero? && (payload.empty? || payload["ok"] != false)
+
+      :failed
+    end
+
+    def write_marker(path, payload, outcome:, exit_code:)
+      marker_path = path.to_s.strip
+      return if marker_path.empty?
+
+      expanded_path = File.expand_path(marker_path)
+      FileUtils.mkdir_p(File.dirname(expanded_path))
+      marker_payload = {
+        ok: outcome == :success,
+        id: @id,
+        outcome: outcome.to_s,
+        exit_code: exit_code,
+        status: payload["status"],
+        work_state: payload["work_state"],
+        task_complete: payload["task_complete"] || payload["event"] == "task_complete",
+        task_failed: payload["task_failed"] || payload["event"] == "task_failed",
+        done: payload["done"],
+        terminal: payload["terminal"],
+        source: "harnex watch"
+      }.compact
+      File.write(expanded_path, JSON.generate(marker_payload) + "\n")
+    end
+
+    def stop_session
+      repo_root = Harnex.resolve_repo_root(@repo_path)
+      registry = Harnex.read_registry(repo_root, @id)
+      return unless registry
+
+      uri = URI("http://#{registry.fetch('host')}:#{registry.fetch('port')}/stop")
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{registry['token']}" if registry["token"]
+
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 2) do |http|
+        http.request(request)
+      end
+      @err.puts("harnex watch: stop-on-terminal failed with HTTP #{response.code}") unless response.is_a?(Net::HTTPSuccess)
+    rescue StandardError => e
+      @err.puts("harnex watch: stop-on-terminal failed: #{e.message}")
+    end
+  end
+
+  class WatchCommand
+    def self.usage(program_name = "harnex watch")
+      <<~TEXT
+        Usage: #{program_name} --id ID [options]
+
+        Options:
+          --id ID              Existing session ID to watch (required)
+          --until done         Watch work-level terminal state (default: done)
+          --repo PATH          Resolve session using PATH's repo root (default: current repo)
+          --max-wait DUR       Wall-clock cap before returning timeout (examples: 900, 15m, 2h)
+          --timeout DUR        Alias for --max-wait
+          --done-marker PATH   Write a JSON marker when work completes successfully
+          --fail-marker PATH   Write a JSON marker when work fails
+          --stop-on-terminal   Stop the live session after success/failure (not on timeout)
+          -h, --help           Show this help
+
+        `harnex watch` is the safe watcher for existing --tmux or detached
+        dispatches. It exits 0 for task_complete/done, non-zero for task_failed
+        or failed terminal summaries, and 124 for --max-wait timeouts.
+
+        For launch-and-babysit stall recovery, use `harnex run --watch`.
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = {
+        id: nil,
+        repo_path: Dir.pwd,
+        until_state: "done",
+        max_wait: nil,
+        done_marker: nil,
+        fail_marker: nil,
+        stop_on_terminal: false,
+        help: false
+      }
+    end
+
+    def run
+      parser.parse!(@argv)
+      if @options[:help]
+        puts self.class.usage
+        return 0
+      end
+
+      raise "--id is required for harnex watch" unless @options[:id]
+
+      TerminalWatcher.new(
+        id: @options[:id],
+        repo_path: @options[:repo_path],
+        until_state: @options[:until_state],
+        max_wait: @options[:max_wait],
+        done_marker: @options[:done_marker],
+        fail_marker: @options[:fail_marker],
+        stop_on_terminal: @options[:stop_on_terminal]
+      ).run
+    end
+
+    private
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: harnex watch --id ID [options]"
+        opts.on("--id ID", "Existing session ID to watch") { |value| @options[:id] = Harnex.normalize_id(value) }
+        opts.on("--until STATE", "Watch until terminal state") { |value| @options[:until_state] = value }
+        opts.on("--repo PATH", "Resolve session using PATH's repo root") { |value| @options[:repo_path] = value }
+        opts.on("--max-wait DUR", "Wall-clock cap") do |value|
+          @options[:max_wait] = Harnex.parse_duration_seconds(value, option_name: "--max-wait")
+        end
+        opts.on("--timeout DUR", "Alias for --max-wait") do |value|
+          @options[:max_wait] = Harnex.parse_duration_seconds(value, option_name: "--timeout")
+        end
+        opts.on("--done-marker PATH", "Write marker on successful completion") { |value| @options[:done_marker] = value }
+        opts.on("--fail-marker PATH", "Write marker on failed completion") { |value| @options[:fail_marker] = value }
+        opts.on("--stop-on-terminal", "Stop live session after success/failure") { @options[:stop_on_terminal] = true }
+        opts.on("-h", "--help", "Show help") { @options[:help] = true }
+      end
+    end
+  end
 end

data/lib/harnex/core.rb

@@ -32,7 +32,7 @@ module Harnex
   ].freeze
 
   def resolve_repo_root(path = Dir.pwd)
-    output, status = Open3.capture2("git", "rev-parse", "--show-toplevel", chdir: path)
+    output, status = Open3.capture2("git", "rev-parse", "--show-toplevel", chdir: path, err: File::NULL)
     status.success? ? output.strip : File.expand_path(path)
   rescue StandardError
     File.expand_path(path)

data/lib/harnex/runtime/session.rb

@@ -58,15 +58,16 @@ module Harnex
       end
     end
 
-    attr_reader :repo_root, :launch_cwd, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch,
+    attr_reader :repo_root, :launch_cwd, :child_cwd, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch,
                 :inbox, :description, :meta, :summary_out, :output_log_path, :events_log_path,
                 :started_at, :ended_at, :exit_code, :term_signal
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
       @launch_cwd = File.expand_path(launch_cwd.to_s.empty? ? repo_root : launch_cwd)
+      @child_cwd = child_cwd.to_s.empty? ? nil : File.expand_path(child_cwd)
       @host = host
       @id = Harnex.normalize_id(id)
       @watch = watch
@@ -153,7 +154,9 @@ module Harnex
     end
 
     def run_pty
-      @reader, @writer, @pid = PTY.spawn(child_env, *command)
+      spawn_args = [child_env, *command]
+      spawn_args << { chdir: child_cwd } if child_cwd
+      @reader, @writer, @pid = PTY.spawn(*spawn_args)
       @writer.sync = true
       arm_auto_stop_after_initial_context
       emit_started_event
@@ -402,7 +405,7 @@ module Harnex
       adapter.on_notification { |msg| handle_structured_notification(msg) }
       adapter.on_disconnect { |err| handle_structured_disconnect(err) }
 
-      adapter.start_rpc(env: child_env, cwd: repo_root)
+      adapter.start_rpc(env: child_env, cwd: child_cwd || repo_root)
       @pid = adapter.pid
       @state_machine.force_prompt!
       emit_started_event
@@ -821,7 +824,7 @@ module Harnex
     def registry_payload
       status_payload(include_input_state: false).merge(
         token: token,
-        cwd: Dir.pwd
+        cwd: child_cwd || Dir.pwd
       )
     end
 

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.7"
-  RELEASE_DATE = "2026-06-12"
+  VERSION = "0.7.9"
+  RELEASE_DATE = "2026-07-10"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.7
+  version: 0.7.9
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex, Pi)
   and adds a control plane for discovery, messaging, and coordination.