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 +4 -4
- data/CHANGELOG.md +16 -0
- data/README.md +28 -13
- data/guides/01_dispatch.md +12 -6
- data/guides/03_buddy.md +8 -1
- data/guides/04_monitoring.md +36 -40
- data/lib/harnex/cli.rb +7 -0
- data/lib/harnex/commands/watch.rb +204 -0
- data/lib/harnex/version.rb +2 -2
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 64a1ddf83ef070cc2b418c1a70ae3e1fc2c8b5fd671e8fa3e5a30536184728ca
|
|
4
|
+
data.tar.gz: 6a076faed04db3eddbaf4bf2fefbee95426cd8ee8008499e3474fbfa1b5c62ed
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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,
|
|
72
|
-
`--wait-for-idle`
|
|
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
|
|
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 --
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
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
|
|
186
|
-
|
|
187
|
-
|
|
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) |
|
data/guides/01_dispatch.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
|
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
|
|
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
|
-
|
|
138
|
-
and monitor the worker. Use pane/log/event polling or a buddy when you
|
|
139
|
-
interpretation
|
|
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
|
|
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"
|
data/guides/04_monitoring.md
CHANGED
|
@@ -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
|
|
21
|
-
work-level `task_complete` or
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
|
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
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
92
|
-
|
|
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
|
|
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
|
-
|
|
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
|
data/lib/harnex/version.rb
CHANGED
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.
|
|
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-
|
|
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.
|