harnex 0.7.7 → 0.7.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: '09276571f581a98eb6c613e88e4035ed8420bcae710c43d57e307cc5eb4d468b'
4
- data.tar.gz: 886e1555b2ee4d128d992e4d35aafc716c0bc2aa16318123b053e5e128a7337a
3
+ metadata.gz: 64a1ddf83ef070cc2b418c1a70ae3e1fc2c8b5fd671e8fa3e5a30536184728ca
4
+ data.tar.gz: 6a076faed04db3eddbaf4bf2fefbee95426cd8ee8008499e3474fbfa1b5c62ed
5
5
  SHA512:
6
- metadata.gz: 90f7f457f829f99424c1f2635706c3231c08bf1cea7329e47b6992fde3aa45e123c40c0d278bf2c9a5c8bc2ecd6d0f742a812320c659c5bbe68fd4ab94df6c9d
7
- data.tar.gz: 65323fa96b6f5c92564b2be10cfe802f846fff1b76079f26cbaa362588dce50ae86a59c250b456058f3acad8ca31f03c9c49b2ad096c85a6aae5510797ff3abb
6
+ metadata.gz: 3508afcbddc0e9afaf17372ca98cb3146d5edc128fb54c6217f8b80be7f81baae0ab7f50feba4b513a9ba46165323f8fb95ddd243df5bd19921b198beb89bbc6
7
+ data.tar.gz: 25419186825ac14d2f6cd844497d6dc356e88785f23784f30492284b80c384781ab834011f394d27c93078821fc394fed3ac97b8bff818f7b60fc280be83a560
data/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.7.8] - 2026-06-13 | 08:45 PM | IST
6
+
7
+ ### Added
8
+
9
+ - `harnex watch --id <id> --until done` now provides a native work-terminal
10
+ watcher for existing visible/detached sessions. It exits `0` for successful
11
+ work, non-zero for `task_failed` / failed terminal telemetry, `124` for
12
+ wall-clock timeout, and can write optional done/fail marker files for legacy
13
+ queue integrations.
14
+
15
+ ### Changed
16
+
17
+ - Monitoring docs now recommend native `harnex watch` for unattended
18
+ single-dispatch monitoring and reserve `harnex run --watch` for foreground
19
+ launch-and-stall-recovery.
20
+
5
21
  ## [0.7.7] - 2026-06-12 | 10:48 AM | IST
6
22
 
7
23
  ### Fixed
data/README.md CHANGED
@@ -68,8 +68,9 @@ job, watch it work, stop it when done.
68
68
  `harnex events` streams structured JSONL lifecycle events.
69
69
 
70
70
  - **You don't want to babysit.** Use `--context --auto-stop` for
71
- one-shot work, `--watch` for bounded stall recovery, or
72
- `--wait-for-idle` as a send fence.
71
+ one-shot work, `harnex watch` for existing visible/detached dispatches,
72
+ `run --watch` for bounded foreground stall recovery, or `--wait-for-idle`
73
+ as a send fence.
73
74
 
74
75
  - **You want local-only orchestration.** Everything runs on your
75
76
  machine. No cloud services, no API keys beyond what the agents need.
@@ -150,18 +151,27 @@ harnex agents-guide monitoring
150
151
 
151
152
  ## Built-in dispatch monitoring
152
153
 
153
- For unattended dispatches, use `--watch` instead of writing a bash poll loop:
154
+ For unattended visible/background dispatches, use `harnex watch` instead of
155
+ writing a bash poll loop around `harnex wait`:
154
156
 
155
157
  ```bash
156
- harnex run pi --id pi-impl-42 --watch --preset impl \
158
+ harnex run pi --id pi-impl-42 --tmux pi-impl-42 \
157
159
  --context "Implement koder/plans/42_plan.md. Run tests and commit when done."
160
+ harnex watch --id pi-impl-42 --until done --max-wait 90m \
161
+ --done-marker /tmp/pi-impl-42-done.json \
162
+ --fail-marker /tmp/pi-impl-42-failed.json
158
163
  ```
159
164
 
160
- `--watch` runs a foreground babysitter that checks session activity every 60s,
161
- force-resumes on stall up to a cap, and exits when the target session exits or
162
- the resume cap is reached. It is foreground-only; use `--tmux` or `--detach`
163
- for visible/background sessions, and `--watch` when the current command should
164
- block as the monitor.
165
+ `harnex watch --until done` is the safe work-terminal watcher for existing
166
+ `--tmux` or detached sessions. It exits `0` for `task_complete`/done, non-zero
167
+ for `task_failed` or failed terminal summaries, and `124` for `--max-wait`
168
+ timeouts. It does not keep pane/status polling after a terminal failure signal.
169
+
170
+ `harnex run --watch` is a separate foreground babysitter that checks session
171
+ activity every 60s, force-resumes on stall up to a cap, and exits when the
172
+ target session exits or the resume cap is reached. It is foreground-only; use
173
+ `--tmux` or `--detach` for visible/background sessions, and `run --watch` when
174
+ the current command should launch and monitor one worker.
165
175
 
166
176
  Presets map to stall policy defaults:
167
177
 
@@ -180,11 +190,15 @@ and stops the session after the first task completion or PTY prompt return.
180
190
 
181
191
  ## Completion and waiting
182
192
 
183
- Choose the wait predicate that matches how you launched the worker:
193
+ Choose the wait/watch predicate that matches how you launched the worker:
184
194
 
185
- - `harnex wait --id ID --until done --timeout SECS` is the safest unattended
186
- work fence. It returns when Harnex sees `task_complete`, `task_failed`, or a
187
- terminal exit, whichever comes first; failed work returns non-zero.
195
+ - `harnex watch --id ID --until done --max-wait DUR` is the safest unattended
196
+ monitor for an existing visible or detached dispatch. It wraps the work-level
197
+ fence, preserves the timeout/failure distinction, and can write done/fail
198
+ marker files for legacy queue integrations.
199
+ - `harnex wait --id ID --until done --timeout SECS` is the primitive work fence.
200
+ It returns when Harnex sees `task_complete`, `task_failed`, or a terminal
201
+ exit, whichever comes first; failed work returns non-zero.
188
202
  - `harnex wait --id ID` waits for the wrapped process to exit. This is right
189
203
  for already-exited sessions and terminal-summary recovery, but interactive
190
204
  agents can stay open after finishing a turn.
@@ -313,6 +327,7 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
313
327
  | `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until the turn returns idle) |
314
328
  | `harnex stop --id <id>` | Send the agent's native exit sequence |
315
329
  | `harnex status` | List running sessions; with `--id ID --json`, terminal summaries can classify completed/failed sessions after exit |
330
+ | `harnex watch --id <id>` | Safely monitor existing visible/detached work until `done`, `task_failed`, or timeout; optional done/fail markers |
316
331
  | `harnex pane --id <id>` | Capture a tmux-backed session's screen (`--follow` for live) |
317
332
  | `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
318
333
  | `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |
@@ -73,7 +73,7 @@ for i in 1 2 3; do
73
73
  harnex run pi --id w-$i --tmux w-$i --detach \
74
74
  --context "Read and execute /tmp/task-$i.md" --auto-stop &
75
75
  done
76
- for i in 1 2 3; do harnex wait --id w-$i --until done & done
76
+ for i in 1 2 3; do harnex watch --id w-$i --until done --max-wait 90m & done
77
77
  wait
78
78
  ```
79
79
 
@@ -125,18 +125,24 @@ Use the lightest primitive that gives the signal you need:
125
125
  | Continuous pane view | `harnex pane --id pi-i-NN --follow` |
126
126
  | Transcript tail | `harnex logs --id pi-i-NN --lines 80` |
127
127
  | Structured events | `harnex events --id pi-i-NN --snapshot` |
128
- | Work completion/failure fence | `harnex wait --id pi-i-NN --until done` |
128
+ | Existing-session work monitor | `harnex watch --id pi-i-NN --until done --max-wait 90m` |
129
+ | Primitive work completion/failure fence | `harnex wait --id pi-i-NN --until done` |
129
130
  | Native successful-turn completion | `harnex wait --id pi-i-NN --until task_complete` |
130
131
 
131
- For unattended policy-only stall recovery, use built-in watch mode:
132
+ For visible `--tmux` or detached dispatches, prefer `harnex watch --id`: it
133
+ returns `0` on done, non-zero on `task_failed`/failed terminal summaries, and
134
+ `124` on `--max-wait` timeout. Use `--done-marker` / `--fail-marker` only as
135
+ compatibility outputs for older queue scripts.
136
+
137
+ For foreground launch-and-stall-recovery, use `harnex run --watch`:
132
138
 
133
139
  ```bash
134
140
  harnex run pi --id pi-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
135
141
  ```
136
142
 
137
- `--watch` is foreground-blocking. Use it when a single process should launch
138
- and monitor the worker. Use pane/log/event polling or a buddy when you need
139
- interpretation, multiple sessions, or a separate watcher.
143
+ `run --watch` is foreground-blocking. Use it when a single process should
144
+ launch and monitor the worker. Use pane/log/event polling or a buddy when you
145
+ need interpretation across multiple sessions.
140
146
 
141
147
  ## Verify And Stop
142
148
 
data/guides/03_buddy.md CHANGED
@@ -4,7 +4,14 @@ A buddy is a second harnex session that watches one or more workers and nudges
4
4
  them if they stall. Use a buddy when the work is long-running, unattended, or
5
5
  needs interpretation that simple stall policy cannot provide.
6
6
 
7
- For simple inactivity recovery, prefer built-in watch mode:
7
+ For simple work-terminal monitoring of an existing visible/detached session,
8
+ prefer the native watcher:
9
+
10
+ ```bash
11
+ harnex watch --id pi-i-NN --until done --max-wait 90m
12
+ ```
13
+
14
+ For foreground launch-and-inactivity recovery, use built-in run watch mode:
8
15
 
9
16
  ```bash
10
17
  harnex run pi --id pi-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
@@ -17,12 +17,15 @@ Prefer signals in this order:
17
17
  | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
18
18
  | `harnex status` | Session liveness and coarse state |
19
19
 
20
- For unattended monitors, prefer `harnex wait --until done`: it returns on the
21
- work-level `task_complete` or `task_failed` signal, or terminal exit, whichever
22
- comes first. Failed work returns non-zero. For structured sessions (Pi RPC and
23
- Codex app-server), `harnex wait --until task_complete` remains the exact
24
- successful-turn fence. Neither knows your acceptance criteria; verify the
25
- expected artifact or tests afterward.
20
+ For unattended monitors on existing visible/detached sessions, prefer
21
+ `harnex watch --until done`: it returns on the work-level `task_complete` or
22
+ `task_failed` signal, or terminal exit, whichever comes first. Successful work
23
+ exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
24
+ callers that need the lower-level primitive, `harnex wait --until done` exposes
25
+ the same work fence. For structured sessions (Pi RPC and Codex app-server),
26
+ `harnex wait --until task_complete` remains the exact successful-turn fence.
27
+ None of these know your acceptance criteria; verify the expected artifact or
28
+ tests afterward.
26
29
 
27
30
  ## Completion Test
28
31
 
@@ -30,15 +33,19 @@ For unattended work, first gate on harnex work completion, then verify the task
30
33
  artifact and repo health:
31
34
 
32
35
  ```bash
33
- harnex wait --id pi-i-NN --until done --timeout 5400 &&
36
+ harnex watch --id pi-i-NN --until done --max-wait 90m \
37
+ --done-marker /tmp/pi-i-NN-done.json \
38
+ --fail-marker /tmp/pi-i-NN-failed.json &&
34
39
  test -f path/to/expected-artifact &&
35
40
  test -z "$(git status --short)"
36
41
  ```
37
42
 
38
- `harnex wait --until done` succeeds from `task_complete` or durable successful
39
- terminal telemetry (`--summary-out` / `.harnex/dispatch.jsonl` / exit status),
40
- returns non-zero for `task_failed` / failed terminal telemetry, and does not use
41
- tmp done markers.
43
+ `harnex watch --until done` wraps the `harnex wait --until done` work fence:
44
+ it succeeds from `task_complete` or durable successful terminal telemetry
45
+ (`--summary-out` / `.harnex/dispatch.jsonl` / exit status), returns non-zero for
46
+ `task_failed` / failed terminal telemetry, returns `124` for `--max-wait`, and
47
+ only writes done/fail markers as compatibility outputs after harnex has seen a
48
+ terminal work signal.
42
49
 
43
50
  Adjust the artifact path to the task. The point is to avoid declaring done while
44
51
  a worker is between edits or between commits.
@@ -76,42 +83,29 @@ harnex events --id pi-i-NN
76
83
  For task completion:
77
84
 
78
85
  ```bash
86
+ harnex watch --id pi-i-NN --until done --max-wait 15m
87
+ # Primitive equivalent when a script wants raw wait semantics:
79
88
  harnex wait --id pi-i-NN --until done --timeout 900
80
- # Or, when you specifically need the structured turn event:
89
+ # Or, when you specifically need the structured successful-turn event:
81
90
  harnex wait --id pi-i-NN --until task_complete --timeout 900
82
91
  ```
83
92
 
84
93
  ## Background Sweeper
85
94
 
86
- Consumers often run a small shell loop that checks terminal state, then drops
87
- to pane diagnostics only while work is still running. Keep a hard wall-clock cap
88
- so an unattended pipeline cannot wait forever:
95
+ Avoid custom shell loops that repeatedly call `harnex wait`/`harnex status` and
96
+ then accidentally swallow a failed work result. For a single unattended
97
+ visible/detached dispatch, use the native watcher with a hard wall-clock cap:
89
98
 
90
99
  ```bash
91
- start=$(date +%s)
92
- max_wait=5400
93
-
94
- while :; do
95
- if test "$(($(date +%s) - start))" -gt "$max_wait"; then
96
- echo "wall-clock cap hit for pi-i-NN" >&2
97
- exit 2
98
- fi
99
-
100
- row=$(harnex status --id pi-i-NN --json | ruby -rjson -e 'rows=JSON.parse(STDIN.read); print JSON.generate(rows.first || {})')
101
- done=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["done"] ? "true" : "false")')
102
- work_state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["work_state"].to_s)')
103
- state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["state"].to_s)')
104
-
105
- case "$done:$work_state" in
106
- true:*) echo "pi-i-NN work completed"; break ;;
107
- false:failed) echo "pi-i-NN work failed; process state: $state" >&2; exit 1 ;;
108
- *) harnex pane --id pi-i-NN --lines 20 ;;
109
- esac
110
-
111
- sleep 60
112
- done
100
+ harnex watch --id pi-i-NN --until done --max-wait 90m \
101
+ --done-marker /tmp/pi-i-NN-done.json \
102
+ --fail-marker /tmp/pi-i-NN-failed.json
113
103
  ```
114
104
 
105
+ If that exits `124`, inspect the pane/logs/events and decide whether to nudge,
106
+ stop, or continue. If it exits any other non-zero code, treat the work as
107
+ failed; do not continue polling the same task as though it were still running.
108
+
115
109
  Recommended caps:
116
110
 
117
111
  | Work type | Cap |
@@ -120,17 +114,18 @@ Recommended caps:
120
114
  | Medium implementation | 90 minutes |
121
115
  | Large unattended phase | 3 hours |
122
116
 
123
- ## Built-In Watch Mode
117
+ ## Built-In Stall Babysitter
124
118
 
125
119
  Use `harnex run --watch` when one foreground process should launch the worker
126
- and apply bounded stall recovery:
120
+ and apply bounded stall recovery. This is different from `harnex watch --id`,
121
+ which watches an existing session's work-terminal state:
127
122
 
128
123
  ```bash
129
124
  harnex run pi --id pi-i-NN --watch --preset impl \
130
125
  --context "Read /tmp/task-impl-NN.md"
131
126
  ```
132
127
 
133
- `--watch` exits with:
128
+ `run --watch` exits with:
134
129
 
135
130
  | Code | Meaning |
136
131
  | --- | --- |
@@ -145,6 +140,7 @@ interpretation.
145
140
 
146
141
  - Polling `state=completed` alone and missing live sessions with `task_complete=true`.
147
142
  - Polling `state=prompt` alone and calling it done.
143
+ - Wrapping `harnex wait` in loops that swallow non-zero `task_failed` results.
148
144
  - Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
149
145
  - Letting an unattended loop run with no wall-clock cap.
150
146
  - Reading raw tmux panes instead of `harnex pane`.
data/lib/harnex/cli.rb CHANGED
@@ -15,6 +15,8 @@ module Harnex
15
15
  Sender.new(@argv.drop(1)).run
16
16
  when "wait"
17
17
  Waiter.new(@argv.drop(1)).run
18
+ when "watch"
19
+ WatchCommand.new(@argv.drop(1)).run
18
20
  when "stop"
19
21
  Stopper.new(@argv.drop(1)).run
20
22
  when "status"
@@ -59,6 +61,8 @@ module Harnex
59
61
  Sender.usage
60
62
  when "wait"
61
63
  Waiter.usage
64
+ when "watch"
65
+ WatchCommand.usage
62
66
  when "stop"
63
67
  Stopper.usage
64
68
  when "status"
@@ -90,6 +94,7 @@ module Harnex
90
94
  harnex run <cli> [options] [--] [cli-args...]
91
95
  harnex send --id ID [options] [text...]
92
96
  harnex wait --id ID [options]
97
+ harnex watch --id ID [options]
93
98
  harnex stop --id ID [options]
94
99
  harnex status [options]
95
100
  harnex logs --id ID [options]
@@ -104,6 +109,7 @@ module Harnex
104
109
  run Start a wrapped interactive session and local API
105
110
  send Send text to an active session
106
111
  wait Block until a session exits or reaches a state
112
+ watch Safely watch existing work until done/task_failed/timeout
107
113
  stop Send the adapter stop sequence to a session
108
114
  status List live sessions
109
115
  logs Read session output transcripts
@@ -129,6 +135,7 @@ module Harnex
129
135
  harnex run aider --id blue-cat
130
136
  harnex run codex -- --cd /path/to/repo
131
137
  harnex status
138
+ harnex watch --id main --until done --max-wait 15m
132
139
  harnex logs --id main --follow
133
140
  harnex events --id main --snapshot
134
141
  harnex history --limit 20
@@ -1,5 +1,8 @@
1
+ require "fileutils"
1
2
  require "json"
2
3
  require "net/http"
4
+ require "optparse"
5
+ require "stringio"
3
6
  require "uri"
4
7
 
5
8
  module Harnex
@@ -206,4 +209,205 @@ module Harnex
206
209
  @monotonic_clock.call
207
210
  end
208
211
  end
212
+
213
+ class TerminalWatcher
214
+ TIMEOUT_EXIT_CODE = 124
215
+
216
+ def initialize(
217
+ id:,
218
+ repo_path: Dir.pwd,
219
+ until_state: "done",
220
+ max_wait: nil,
221
+ done_marker: nil,
222
+ fail_marker: nil,
223
+ stop_on_terminal: false,
224
+ out: $stdout,
225
+ err: $stderr
226
+ )
227
+ @id = Harnex.normalize_id(id)
228
+ @repo_path = repo_path
229
+ @until_state = until_state.to_s.strip.empty? ? "done" : until_state.to_s
230
+ @max_wait = max_wait
231
+ @done_marker = done_marker
232
+ @fail_marker = fail_marker
233
+ @stop_on_terminal = stop_on_terminal
234
+ @out = out
235
+ @err = err
236
+ end
237
+
238
+ def run
239
+ raise "harnex watch: only --until done is supported" unless @until_state == "done"
240
+
241
+ output, warnings, exit_code = capture_wait
242
+ @err.write(warnings) unless warnings.empty?
243
+ @out.write(output) unless output.empty?
244
+
245
+ payload = parse_payload(output)
246
+ outcome = classify(exit_code, payload)
247
+ case outcome
248
+ when :success
249
+ write_marker(@done_marker, payload, outcome: outcome, exit_code: exit_code)
250
+ when :failed
251
+ write_marker(@fail_marker, payload, outcome: outcome, exit_code: exit_code)
252
+ end
253
+
254
+ stop_session if @stop_on_terminal && outcome != :timeout
255
+ exit_code
256
+ end
257
+
258
+ private
259
+
260
+ def capture_wait
261
+ argv = ["--id", @id, "--repo", @repo_path, "--until", @until_state]
262
+ argv += ["--timeout", @max_wait.to_s] if @max_wait
263
+
264
+ out_buffer = StringIO.new
265
+ err_buffer = StringIO.new
266
+ original_stdout = $stdout
267
+ original_stderr = $stderr
268
+ $stdout = out_buffer
269
+ $stderr = err_buffer
270
+ exit_code = Waiter.new(argv).run
271
+ [out_buffer.string, err_buffer.string, exit_code]
272
+ ensure
273
+ $stdout = original_stdout
274
+ $stderr = original_stderr
275
+ end
276
+
277
+ def parse_payload(output)
278
+ line = output.to_s.lines.reverse.find { |candidate| !candidate.strip.empty? }
279
+ return {} unless line
280
+
281
+ parsed = JSON.parse(line)
282
+ parsed.is_a?(Hash) ? parsed : {}
283
+ rescue JSON::ParserError
284
+ {}
285
+ end
286
+
287
+ def classify(exit_code, payload)
288
+ return :timeout if exit_code == TIMEOUT_EXIT_CODE || payload["status"].to_s == "timeout"
289
+ return :success if exit_code.to_i.zero? && (payload.empty? || payload["ok"] != false)
290
+
291
+ :failed
292
+ end
293
+
294
+ def write_marker(path, payload, outcome:, exit_code:)
295
+ marker_path = path.to_s.strip
296
+ return if marker_path.empty?
297
+
298
+ expanded_path = File.expand_path(marker_path)
299
+ FileUtils.mkdir_p(File.dirname(expanded_path))
300
+ marker_payload = {
301
+ ok: outcome == :success,
302
+ id: @id,
303
+ outcome: outcome.to_s,
304
+ exit_code: exit_code,
305
+ status: payload["status"],
306
+ work_state: payload["work_state"],
307
+ task_complete: payload["task_complete"] || payload["event"] == "task_complete",
308
+ task_failed: payload["task_failed"] || payload["event"] == "task_failed",
309
+ done: payload["done"],
310
+ terminal: payload["terminal"],
311
+ source: "harnex watch"
312
+ }.compact
313
+ File.write(expanded_path, JSON.generate(marker_payload) + "\n")
314
+ end
315
+
316
+ def stop_session
317
+ repo_root = Harnex.resolve_repo_root(@repo_path)
318
+ registry = Harnex.read_registry(repo_root, @id)
319
+ return unless registry
320
+
321
+ uri = URI("http://#{registry.fetch('host')}:#{registry.fetch('port')}/stop")
322
+ request = Net::HTTP::Post.new(uri)
323
+ request["Authorization"] = "Bearer #{registry['token']}" if registry["token"]
324
+
325
+ response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 2) do |http|
326
+ http.request(request)
327
+ end
328
+ @err.puts("harnex watch: stop-on-terminal failed with HTTP #{response.code}") unless response.is_a?(Net::HTTPSuccess)
329
+ rescue StandardError => e
330
+ @err.puts("harnex watch: stop-on-terminal failed: #{e.message}")
331
+ end
332
+ end
333
+
334
+ class WatchCommand
335
+ def self.usage(program_name = "harnex watch")
336
+ <<~TEXT
337
+ Usage: #{program_name} --id ID [options]
338
+
339
+ Options:
340
+ --id ID Existing session ID to watch (required)
341
+ --until done Watch work-level terminal state (default: done)
342
+ --repo PATH Resolve session using PATH's repo root (default: current repo)
343
+ --max-wait DUR Wall-clock cap before returning timeout (examples: 900, 15m, 2h)
344
+ --timeout DUR Alias for --max-wait
345
+ --done-marker PATH Write a JSON marker when work completes successfully
346
+ --fail-marker PATH Write a JSON marker when work fails
347
+ --stop-on-terminal Stop the live session after success/failure (not on timeout)
348
+ -h, --help Show this help
349
+
350
+ `harnex watch` is the safe watcher for existing --tmux or detached
351
+ dispatches. It exits 0 for task_complete/done, non-zero for task_failed
352
+ or failed terminal summaries, and 124 for --max-wait timeouts.
353
+
354
+ For launch-and-babysit stall recovery, use `harnex run --watch`.
355
+ TEXT
356
+ end
357
+
358
+ def initialize(argv)
359
+ @argv = argv.dup
360
+ @options = {
361
+ id: nil,
362
+ repo_path: Dir.pwd,
363
+ until_state: "done",
364
+ max_wait: nil,
365
+ done_marker: nil,
366
+ fail_marker: nil,
367
+ stop_on_terminal: false,
368
+ help: false
369
+ }
370
+ end
371
+
372
+ def run
373
+ parser.parse!(@argv)
374
+ if @options[:help]
375
+ puts self.class.usage
376
+ return 0
377
+ end
378
+
379
+ raise "--id is required for harnex watch" unless @options[:id]
380
+
381
+ TerminalWatcher.new(
382
+ id: @options[:id],
383
+ repo_path: @options[:repo_path],
384
+ until_state: @options[:until_state],
385
+ max_wait: @options[:max_wait],
386
+ done_marker: @options[:done_marker],
387
+ fail_marker: @options[:fail_marker],
388
+ stop_on_terminal: @options[:stop_on_terminal]
389
+ ).run
390
+ end
391
+
392
+ private
393
+
394
+ def parser
395
+ @parser ||= OptionParser.new do |opts|
396
+ opts.banner = "Usage: harnex watch --id ID [options]"
397
+ opts.on("--id ID", "Existing session ID to watch") { |value| @options[:id] = Harnex.normalize_id(value) }
398
+ opts.on("--until STATE", "Watch until terminal state") { |value| @options[:until_state] = value }
399
+ opts.on("--repo PATH", "Resolve session using PATH's repo root") { |value| @options[:repo_path] = value }
400
+ opts.on("--max-wait DUR", "Wall-clock cap") do |value|
401
+ @options[:max_wait] = Harnex.parse_duration_seconds(value, option_name: "--max-wait")
402
+ end
403
+ opts.on("--timeout DUR", "Alias for --max-wait") do |value|
404
+ @options[:max_wait] = Harnex.parse_duration_seconds(value, option_name: "--timeout")
405
+ end
406
+ opts.on("--done-marker PATH", "Write marker on successful completion") { |value| @options[:done_marker] = value }
407
+ opts.on("--fail-marker PATH", "Write marker on failed completion") { |value| @options[:fail_marker] = value }
408
+ opts.on("--stop-on-terminal", "Stop live session after success/failure") { @options[:stop_on_terminal] = true }
409
+ opts.on("-h", "--help", "Show help") { @options[:help] = true }
410
+ end
411
+ end
412
+ end
209
413
  end
@@ -1,4 +1,4 @@
1
1
  module Harnex
2
- VERSION = "0.7.7"
3
- RELEASE_DATE = "2026-06-12"
2
+ VERSION = "0.7.8"
3
+ RELEASE_DATE = "2026-06-13"
4
4
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: harnex
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.7.7
4
+ version: 0.7.8
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jikku Jose
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-06-12 00:00:00.000000000 Z
11
+ date: 2026-06-13 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: A local PTY harness that wraps terminal AI agents (Claude, Codex, Pi)
14
14
  and adds a control plane for discovery, messaging, and coordination.