@harness-reins/linux-x64 0.0.0-stage → 0.9.2
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.
- package/dist/reins/_internal/base_library.zip +0 -0
- package/dist/reins/_internal/harness_reins/_build.txt +1 -0
- package/dist/reins/_internal/harness_reins/assets/skills/claude/SKILL.md +144 -0
- package/dist/reins/_internal/harness_reins/assets/skills/codex/SKILL.md +88 -0
- package/dist/reins/_internal/harness_reins/assets/skills/pi/SKILL.md +98 -0
- package/dist/reins/_internal/harness_reins/assets/skills/reference/SKILL.md +812 -0
- package/dist/reins/_internal/harness_reins/assets/skills/reference/agents/openai.yaml +4 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/desktop-package-launch.py +263 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/invoke-desktop-package.ps1 +14 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/probe-desktop-launch.py +217 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/start-desktop-bridge.ps1 +449 -0
- package/dist/reins/_internal/harness_reins/harness/pi/extension/reins-callback.js +272 -0
- package/dist/reins/_internal/harness_reins/owners/windows_scheduler.ps1 +156 -0
- package/dist/reins/_internal/harness_reins/templates/test.md +38 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/INSTALLER +1 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/METADATA +18 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/RECORD +199 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/REQUESTED +0 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/WHEEL +5 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/direct_url.json +1 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/entry_points.txt +3 -0
- package/dist/reins/_internal/harness_reins-0.9.2.dist-info/top_level.txt +1 -0
- package/dist/reins/_internal/lib-dynload/_bisect.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_blake2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_bz2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_cn.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_hk.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_iso2022.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_jp.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_kr.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_tw.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_contextvars.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_csv.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_ctypes.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_datetime.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_decimal.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_hashlib.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_heapq.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_json.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_lzma.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_md5.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_multibytecodec.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_opcode.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_pickle.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_posixsubprocess.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_random.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha1.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha3.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_socket.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_ssl.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_statistics.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_struct.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_uuid.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/array.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/binascii.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/fcntl.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/grp.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/math.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/pyexpat.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/resource.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/select.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/termios.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/unicodedata.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/zlib.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/libbz2.so.1.0 +0 -0
- package/dist/reins/_internal/libcrypto.so.1.1 +0 -0
- package/dist/reins/_internal/libffi.so.7 +0 -0
- package/dist/reins/_internal/liblzma.so.5 +0 -0
- package/dist/reins/_internal/libpython3.12.so.1.0 +0 -0
- package/dist/reins/_internal/libssl.so.1.1 +0 -0
- package/dist/reins/_internal/libuuid.so.1 +0 -0
- package/dist/reins/_internal/libz.so.1 +0 -0
- package/dist/reins/_internal/yaml/_yaml.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/reins +0 -0
- package/package.json +14 -4
- package/README.md +0 -3
|
@@ -0,0 +1,812 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: harness-reins
|
|
3
|
+
description: Submit durable Codex, Claude or Pi child agents using registered task templates, or arrange callbacks for long-running commands, training, benchmarks, tests, builds and data jobs. Use when independent task ownership or a return to the original Codex, Claude Code or PI Agent session is needed. Repair Reins configuration status blocks; inspect results, ACK callbacks and continue the original goal.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Harness Reins
|
|
7
|
+
|
|
8
|
+
## Rule
|
|
9
|
+
|
|
10
|
+
Use an explicit callback when requested or when a command may outlive the current Codex or Claude
|
|
11
|
+
Code turn.
|
|
12
|
+
|
|
13
|
+
There are three public workflows:
|
|
14
|
+
|
|
15
|
+
- `reins run -- <command>` submits a new long-running task. The daemon launches it through an independent task owner (systemd on Linux, launchd on macOS, Task Scheduler on Windows; screen fallback on Linux/macOS).
|
|
16
|
+
- `reins agent codex|claude|pi -- <prompt>` submits a fresh child agent through the same durable
|
|
17
|
+
lifecycle. Codex/Claude are available since `0.6.5`; Pi is a child worker and callback
|
|
18
|
+
parent in the current preview.
|
|
19
|
+
- `reins done ...` queues a completion callback for work already owned by screen, tmux,
|
|
20
|
+
Slurm, another scheduler, or an existing script.
|
|
21
|
+
|
|
22
|
+
Daemon handoff is unconditional and requires no opt-in flag. Never add `--via-daemon` to newly
|
|
23
|
+
written commands; old scripts may still pass it as a hidden no-op compatibility flag. Do not
|
|
24
|
+
invent another public launch flag or a direct-mode flag. Do not use a direct recursive
|
|
25
|
+
`codex exec resume` or `claude -p --resume` call from an agent tool sandbox. Do not let callback
|
|
26
|
+
behavior change the task's original exit code unless the user explicitly requests `--strict`.
|
|
27
|
+
|
|
28
|
+
## Registered task templates
|
|
29
|
+
|
|
30
|
+
`reins template register NAME --file /path/to/template.yaml` installs a user template,
|
|
31
|
+
copies its system-prompt dependencies, and creates a short `reins-NAME` discovery skill.
|
|
32
|
+
The YAML's `worker` and `description` describe the capability; CLI options can supply
|
|
33
|
+
or override them. `reins template list --json` shows the registered capabilities.
|
|
34
|
+
The generated entrypoint binds the installed template file so another workspace's
|
|
35
|
+
`REINS_TEMPLATE_DIR` cannot select a different same-named template. Keep Agent profile
|
|
36
|
+
settings and the current parent's callback binding.
|
|
37
|
+
|
|
38
|
+
Read the matching entrypoint and pass actual task scope, target paths and evidence
|
|
39
|
+
constraints. Check readiness with `reins doctor --operation agent --agent-worker WORKER`
|
|
40
|
+
and validate submission with `--dry-run` when needed. Routine local edits need not be
|
|
41
|
+
delegated. On completion, inspect the real result and edits, ACK and continue.
|
|
42
|
+
|
|
43
|
+
Registration maintains only the following index; preserve the surrounding instructions.
|
|
44
|
+
|
|
45
|
+
<!-- reins:registered-templates:begin -->
|
|
46
|
+
<!-- reins:registered-templates:end -->
|
|
47
|
+
|
|
48
|
+
## Callback rules that always apply
|
|
49
|
+
|
|
50
|
+
### Callback modes (0.7.1 preview)
|
|
51
|
+
|
|
52
|
+
`--callback-mode auto` recognizes the current Codex Desktop origin marker and
|
|
53
|
+
selects `desktop`; other origins select `cli`. Use an explicit mode if the host
|
|
54
|
+
omits that marker. A historical session source is not its current owner.
|
|
55
|
+
`desktop` requires a verified shared Core and never silently falls back to a
|
|
56
|
+
second CLI writer. An unavailable Desktop connection refuses a new `run` or
|
|
57
|
+
`agent` before task admission. `done` still preserves already completed work.
|
|
58
|
+
Do not force CLI mode to conceal a Desktop ownership conflict.
|
|
59
|
+
|
|
60
|
+
`manual` explicitly saves results/callbacks for later receipt and does not start
|
|
61
|
+
an Agent automatically. Choose it only when the user accepts this limitation.
|
|
62
|
+
On Mac and Windows, `reins setup` automatically generates a private double-click
|
|
63
|
+
launcher bound to the installed Python and current profile: `.command` on Mac,
|
|
64
|
+
`.cmd` plus `.ps1` on Windows. `setup --desktop-app PATH` selects a Mac `.app`
|
|
65
|
+
or Windows `.exe`; `--no-desktop-launcher` skips generation. Missing Desktop does
|
|
66
|
+
not block CLI setup. Mac discovers the app during preparation; Windows resolves
|
|
67
|
+
the Store manifest and matching Core during launch/preflight. Windows helpers
|
|
68
|
+
ship inside the wheel; do not depend on a checkout or its examples directory.
|
|
69
|
+
Generated absolute paths belong to that machine; regenerate them after moving
|
|
70
|
+
the Python installation rather than copying another user's files.
|
|
71
|
+
`reins desktop prepare` is available for later configuration changes;
|
|
72
|
+
`reins desktop launch --check-only` checks launch blockers, and `reins desktop launch`
|
|
73
|
+
requires existing Desktop work to be saved and the app closed. Obtain permission
|
|
74
|
+
before interrupting active Desktop work. Preparation and checks need no restart.
|
|
75
|
+
Windows defaults to direct startup. `setup --desktop-launch-mode package-context`
|
|
76
|
+
or `desktop prepare --launch-mode package-context --force` saves the explicitly
|
|
77
|
+
chosen experimental Store route. Never silently fall back to this diagnostic
|
|
78
|
+
context after an access-denied failure. `--check-only` uses the existing suspended
|
|
79
|
+
creation/cleanup probe; it is not GUI/tool/callback acceptance. Ordinary setup
|
|
80
|
+
only generates files and performs no native GUI creation probe.
|
|
81
|
+
|
|
82
|
+
Read `doctor`'s separate `callback` field. `owner_reachable` is a read-only
|
|
83
|
+
observation, not proof of end-to-end receipt. Sandboxed tools may need authorized
|
|
84
|
+
ordinary-user execution to inspect native peers; never weaken identity checks.
|
|
85
|
+
After repairing a known failed handoff, `reins retry --id ID --callback-mode desktop`
|
|
86
|
+
requeues the original callback without rerunning its workload. Unknown submission
|
|
87
|
+
outcomes, active deliveries, ACKs and cancellations prevent ordinary retry.
|
|
88
|
+
Inspect manual results in the bound session before ACK, and label that receipt
|
|
89
|
+
as manual rather than a successful autonomous callback test.
|
|
90
|
+
|
|
91
|
+
Upgrade the coordinator before using new task record v3 / callback record v2.
|
|
92
|
+
Older daemons deliberately reject them instead of dropping callback-mode intent.
|
|
93
|
+
|
|
94
|
+
On every callback, inspect the result and relevant artifacts, decide whether the
|
|
95
|
+
original goal is complete, blocked, or needs another action, and continue when the
|
|
96
|
+
next step is clear and safe. Inspect existing work before relaunching it. Then run
|
|
97
|
+
the supplied ACK command; ACK confirms receipt, not completion of the overall goal.
|
|
98
|
+
Resume only the bound conversation, never redirect to another session.
|
|
99
|
+
|
|
100
|
+
Read the user callback hook at initial Reins use when present. Its instructions still
|
|
101
|
+
apply when not repeated. Since Reins 0.6.6, standard reminders appear on the first callback and every
|
|
102
|
+
4 distinct callbacks thereafter; user-hook reminders on the first and every 3.
|
|
103
|
+
A short callback omits repeated prose, not these responsibilities. Task results,
|
|
104
|
+
routing and the ACK command remain present. In 0.7.0, full commands, timestamps and handoff text are saved at the supplied Details path. Read that file before acting when the envelope says so; otherwise inspect relevant result artifacts directly. An exit code is process status, not proof of test success.
|
|
105
|
+
When reporting a callback to the user, include the recorded task runtime in one
|
|
106
|
+
short phrase when available, such as `Finished in 2m 5.5s`. Use execution duration,
|
|
107
|
+
not the time spent waiting for delivery; do not invent a duration when it is unknown.
|
|
108
|
+
|
|
109
|
+
Configure with `reins prompt-policy --system-every 4 --user-every 3`; no options shows
|
|
110
|
+
the effective policy. `1` means every callback. The file is
|
|
111
|
+
`${REINS_HOME:-~/.reins}/callback-prompts.yaml`. Counters are per
|
|
112
|
+
queue, agent and bound session, allocated at first delivery attempt. Retries reuse
|
|
113
|
+
the same sequence and reminder decisions across restarts. Queuing/dry-run does not
|
|
114
|
+
count.
|
|
115
|
+
|
|
116
|
+
## Ownership invariant
|
|
117
|
+
|
|
118
|
+
The 0.7 topology separates the coordinator and task owners:
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
systemd user service / macOS LaunchAgent / Windows login task -> reins daemon (recovery and callbacks)
|
|
122
|
+
independent systemd service / launchd job / Windows scheduled runner -> Reins worker -> command / child agent
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`--backend auto` prefers an available systemd user manager (v240+) on Linux or
|
|
126
|
+
the logged-in GUI launchd domain on macOS, otherwise screen on those platforms.
|
|
127
|
+
On Windows it selects `windows-task`, using Task Scheduler in the logged-in user
|
|
128
|
+
session and a runner-owned Job Object. `--backend systemd`, `--backend launchd`
|
|
129
|
+
or `--backend windows-task` requires that native manager; `--backend screen` explicitly
|
|
130
|
+
selects the compatibility backend. Existing screen tasks retain their owner. The
|
|
131
|
+
native backend needs no screen. A screen process can remain inside its launching
|
|
132
|
+
service's control group: do not assume it survives stopping that service.
|
|
133
|
+
|
|
134
|
+
After submission, record the task ID, execution backend and artifact paths, then
|
|
135
|
+
return control when no independent work remains. For long work, avoid polling
|
|
136
|
+
processes or logs on a timer. Live monitoring is appropriate when requested or
|
|
137
|
+
diagnosing callback infrastructure. Do not change a running task's owner or
|
|
138
|
+
automatically retry an unknown native launch. DSH remains unsupported.
|
|
139
|
+
|
|
140
|
+
## Duration policy
|
|
141
|
+
|
|
142
|
+
Choose the execution path before launching the command:
|
|
143
|
+
|
|
144
|
+
- If the command is reliably expected to finish within 60 seconds, one foreground wait is
|
|
145
|
+
acceptable.
|
|
146
|
+
- If it may take about one minute or longer, its duration is uncertain, or a second status check
|
|
147
|
+
might be needed, use `reins run` from the start.
|
|
148
|
+
- Do not keep a prompt cache warm by polling. A few-minute task should normally use callback
|
|
149
|
+
delivery: the daemon and screen wait without model turns, then resume the same conversation
|
|
150
|
+
when work completes; ACK and existing-artifact checks handle possible duplicate delivery.
|
|
151
|
+
- If intermediate results genuinely require agent decisions, use sparse milestone callbacks
|
|
152
|
+
rather than timer-based status polling.
|
|
153
|
+
|
|
154
|
+
If a supposedly short foreground command unexpectedly remains active, keep the current turn
|
|
155
|
+
responsible for it; do not abandon it as an agent-owned background process.
|
|
156
|
+
|
|
157
|
+
The command name is `reins`.
|
|
158
|
+
|
|
159
|
+
## Install
|
|
160
|
+
|
|
161
|
+
### Automatic configuration checks
|
|
162
|
+
|
|
163
|
+
`reins run`, `reins agent` and `reins done` automatically check Reins's supported environment,
|
|
164
|
+
configuration and observed runtime chain: storage, coordinator, recorded task
|
|
165
|
+
owners, saved results and callback handoff. These checks follow the selected
|
|
166
|
+
platform adapter and each task's recorded backend, not a fixed list of software
|
|
167
|
+
to install on every host.
|
|
168
|
+
Healthy calls add no diagnostic text. A failed check appends a JSON block between
|
|
169
|
+
`[reins-status]` and `[/reins-status]` on stderr. This is an action request to the
|
|
170
|
+
**calling Agent**: diagnose the listed issues, configure Reins in the current
|
|
171
|
+
environment, run its `recheck_command`, then continue the user's task. Do not hand
|
|
172
|
+
ordinary installation, service startup or configuration commands back to the user.
|
|
173
|
+
|
|
174
|
+
The block supplies `repair_command` and `recheck_command` as argument arrays pinned
|
|
175
|
+
to the current Reins installation and queue. Address missing prerequisites first;
|
|
176
|
+
preserve the original Agent session, profile paths and existing custom settings.
|
|
177
|
+
Read `environment`, `checks.configuration`, `checks.runtime` and each issue's
|
|
178
|
+
`kind`/`code` to distinguish missing setup from a runtime fault or unsupported OS.
|
|
179
|
+
`repair_command` can be null: an absent task owner or unresolved delivery needs
|
|
180
|
+
artifact/session inspection and lifecycle recovery, not a generic reinstall.
|
|
181
|
+
Windows checks Task Scheduler, private state and coordinator identity; macOS checks
|
|
182
|
+
launchd/screen readiness. Repair commands follow the selected platform and queue.
|
|
183
|
+
The setup repair uses `--keep-skill` to retain an installed skill while installing
|
|
184
|
+
one when missing. It can update the Reins coordinator configuration; inspect existing
|
|
185
|
+
service customizations before doing so. Never replace a missing binding with an
|
|
186
|
+
invented session.
|
|
187
|
+
For `done`, repair adds `setup --callback-only`: externally owned work needs the
|
|
188
|
+
callback coordinator, not a local business-task execution backend.
|
|
189
|
+
|
|
190
|
+
Check `work.state` before retrying: `task_persisted` or `callback_queued` means
|
|
191
|
+
repair the infrastructure around that existing ID, **do not submit it again**.
|
|
192
|
+
For `unknown`, inspect that ID's task/queue records before deciding whether a retry
|
|
193
|
+
is needed. For `not_submitted`, retry the original Reins invocation only after the
|
|
194
|
+
prerequisites pass. A `done` invocation reports work already performed; repair or
|
|
195
|
+
retry its callback without rerunning that work.
|
|
196
|
+
|
|
197
|
+
Use `reins doctor` for an explicit JSON check (exit 0 for local readiness, 1 for
|
|
198
|
+
configuration needed). Pass the same queue, backend and session options; for a
|
|
199
|
+
child task include `--operation agent --agent-worker <agent>`. Readiness checks
|
|
200
|
+
local state and observed liveness, not task progress, authentication, the
|
|
201
|
+
coordinator's environment or end-to-end session delivery. An idle queue needs no
|
|
202
|
+
screen session; a durable task result takes precedence over a vanished owner.
|
|
203
|
+
An unavailable owner query is unknown, not proof of a dead task. Saved results
|
|
204
|
+
without callback handoff after a short grace period and unacknowledged failed
|
|
205
|
+
deliveries need attention; acknowledged/canceled history does not. After each
|
|
206
|
+
repair, recheck and use the new evidence. If a repair
|
|
207
|
+
does not resolve its issue, investigate rather than repeat it unchanged. Ask the
|
|
208
|
+
user only for an indispensable login/authorization or unavailable information,
|
|
209
|
+
with the specific blocker; do not ask them to perform routine configuration.
|
|
210
|
+
|
|
211
|
+
Checks do not change command exit semantics, install software or start services
|
|
212
|
+
themselves. Help, dry-runs, private workers and ACK/cancel paths remain available
|
|
213
|
+
without this automatic check.
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
# Install screen only if using the compatibility backend.
|
|
217
|
+
python3 -m pip install "git+https://github.com/lz59970062/harness-reins.git@codex/macos-desktop-callback"
|
|
218
|
+
reins setup --force --enable --now
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`setup` installs this skill for Codex and Claude Code and configures the selected coordinator service. It requires a reachable native manager (systemd/launchd/Task Scheduler) or screen for the Linux/macOS compatibility backend. It creates the user-editable fixed prompt hook at
|
|
222
|
+
`${REINS_HOME:-~/.reins}/callback-hook.md` without overwriting existing content.
|
|
223
|
+
The delivery worker reads that UTF-8 file on attempts whose saved user-reminder decision is
|
|
224
|
+
due, so edits apply on the next due attempt without a restart. Non-empty content is appended
|
|
225
|
+
under `[reins-user-hook]`; hook read failures warn and continue with the callback.
|
|
226
|
+
|
|
227
|
+
`setup` also checks for the Claude Code CLI and runs `claude auth status` with output suppressed.
|
|
228
|
+
This check is advisory and must not block Codex-only installation or print credentials/account
|
|
229
|
+
details. Claude configuration must be present in the shell that later submits `reins agent claude`.
|
|
230
|
+
|
|
231
|
+
### Linux: systemd service hardening
|
|
232
|
+
|
|
233
|
+
The systemd user unit runs the coordinator with `NoNewPrivileges=yes`, and the
|
|
234
|
+
coordinator starts the agent CLIs recorded in the unit (`REINS_CODEX_BIN`,
|
|
235
|
+
`REINS_CLAUDE_BIN`, `REINS_PI_BIN`) for headless callback resumes and child agents.
|
|
236
|
+
A CLI that is really a launcher re-executing through `sudo` or another setuid
|
|
237
|
+
helper works in a login shell but fails inside the service (for example
|
|
238
|
+
`sudo: effective uid is not 0 ...`), so every headless callback fails and lands
|
|
239
|
+
in `failed` after its retries. `setup` and an explicit `reins doctor` start each
|
|
240
|
+
recorded CLI with `--version` in a transient unit carrying the same properties
|
|
241
|
+
(`systemd-run --user --wait --pipe -p NoNewPrivileges=yes`). A CLI that runs
|
|
242
|
+
without the property but not with it is reported as
|
|
243
|
+
`agent_cli_blocked_by_service_sandbox`, naming the binary and its stderr line.
|
|
244
|
+
Automatic checks after `run`, `agent` and `done` do not start agent CLIs.
|
|
245
|
+
|
|
246
|
+
To fix it, prefer rerunning setup with `--claude-bin`, `--codex-bin` or
|
|
247
|
+
`--pi-bin` pointing at a CLI that needs no privilege escalation. If the
|
|
248
|
+
launcher is required, **ask the user first**, then run
|
|
249
|
+
`reins setup --force --now --allow-privilege-escalation`: it writes the unit
|
|
250
|
+
without `NoNewPrivileges=yes` and marks it, so a later doctor repair keeps the
|
|
251
|
+
opt-out. The doctor reports no `repair_command` for this issue alone, because
|
|
252
|
+
weakening the hardening is the user's decision.
|
|
253
|
+
|
|
254
|
+
## Windows
|
|
255
|
+
|
|
256
|
+
Use Windows 10+, Python 3.9+, an ACL-capable local filesystem such as NTFS, and
|
|
257
|
+
the ordinary logged-in user's Task Scheduler session. `--backend auto` and
|
|
258
|
+
`--service auto` select `windows-task`; screen and WSL are unnecessary. Install
|
|
259
|
+
from the release checkout in PowerShell without activating the venv:
|
|
260
|
+
|
|
261
|
+
```powershell
|
|
262
|
+
git clone --branch codex/macos-desktop-callback --depth 1 https://github.com/lz59970062/harness-reins.git
|
|
263
|
+
Set-Location harness-reins
|
|
264
|
+
py -3 -m venv .venv
|
|
265
|
+
& .\.venv\Scripts\python.exe -m pip install .
|
|
266
|
+
& .\.venv\Scripts\reins.exe setup --service windows-task --force --enable --now
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Keep the installed runtime at its fixed path. Setup pins the Agent profiles,
|
|
270
|
+
executables, PATH and queue in a private configuration file. One Agent profile
|
|
271
|
+
has one coordinator queue. For another queue, use a separate profile, or drain
|
|
272
|
+
the current tasks and callbacks, run `reins uninstall-windows-task`, then reinstall
|
|
273
|
+
for the new queue. Do not copy another machine's session binding.
|
|
274
|
+
|
|
275
|
+
Use native argument lists. Recognized npm/forwarding `.cmd` launchers are resolved
|
|
276
|
+
without a shell; unsupported wrappers require their underlying executable.
|
|
277
|
+
Windows callbacks default to CLI resume of the actual original session. An
|
|
278
|
+
experimental shared-server bridge is available only through explicit setup;
|
|
279
|
+
its package-context route passed real Desktop original-session receipt/ACK on
|
|
280
|
+
2026-09-27 on one tested installation. It remains experimental. Execute the callback's emitted
|
|
281
|
+
PowerShell ACK verbatim, including its leading `&` and quoted paths. ACK confirms
|
|
282
|
+
receipt only, not goal completion. Never replace the target with another session.
|
|
283
|
+
|
|
284
|
+
A live Windows test with Codex 0.153.4 could not resume its open Desktop session:
|
|
285
|
+
the CLI reported `already has an active writer`. Ending an Agent turn does not
|
|
286
|
+
guarantee that Desktop releases this owner. Preserve the failed callback and
|
|
287
|
+
report this transport limitation; do not delete Codex's writer lock, forge an
|
|
288
|
+
ACK, change the bound session or rerun the business work. Native workload and
|
|
289
|
+
fake-Agent delivery tests do not establish live original-session receipt.
|
|
290
|
+
|
|
291
|
+
For the experimental bridge, follow the repository's `docs/windows-desktop-bridge.md`.
|
|
292
|
+
It requires Desktop and Reins to use one App Server and the explicit
|
|
293
|
+
`REINS_DESKTOP_BRIDGE_FILE` metadata path. Never guess a port or
|
|
294
|
+
expose an unauthenticated App Server. The supplied launcher refuses a running
|
|
295
|
+
Desktop; switching its connection requires closing active Desktop work first.
|
|
296
|
+
After explicit bridge selection, connection failure must not fall back to CLI.
|
|
297
|
+
|
|
298
|
+
New private files/directories grant only the current user and SYSTEM access.
|
|
299
|
+
Do not weaken those ACLs to work around an Agent sandbox's restricted token;
|
|
300
|
+
authorized native setup/tests may need an ordinary user process outside that
|
|
301
|
+
sandbox. Flushed file data and write-through replacement do not provide a
|
|
302
|
+
POSIX directory-fsync guarantee: namespace changes may be lost after sudden
|
|
303
|
+
power failure. Login is required; sleep pauses work and logout/reboot can
|
|
304
|
+
interrupt it. Missing owners and unknown launches never authorize auto-replay.
|
|
305
|
+
|
|
306
|
+
Use `reins install-windows-task --print` for the public registration preview,
|
|
307
|
+
`reins doctor --backend windows-task` with the original session and queue for
|
|
308
|
+
diagnosis, and `reins setup --service windows-task --keep-skill --force --enable --now`
|
|
309
|
+
after upgrading. A verified coordinator waits for deliveries to drain before
|
|
310
|
+
its supervisor replaces it. `reins uninstall-windows-task` removes the login
|
|
311
|
+
registration and drains the coordinator; it does not stop business tasks or
|
|
312
|
+
erase results/ACKs. Do not delete lock files while inherited delivery handles
|
|
313
|
+
may still own them. See the repository's `docs/windows.md` and validation record.
|
|
314
|
+
|
|
315
|
+
## macOS
|
|
316
|
+
|
|
317
|
+
`reins setup --force --enable --now` selects a user LaunchAgent in the logged-in GUI
|
|
318
|
+
session and independent one-shot launchd jobs for new tasks. Screen is optional.
|
|
319
|
+
Use `reins install-launchd --print` to preview the plist, `--backend launchd` to
|
|
320
|
+
require the native task owner, or `--backend screen --service standalone` for
|
|
321
|
+
headless sessions without a GUI domain. Apple's bundled screen is supported.
|
|
322
|
+
|
|
323
|
+
Task plists live in private task directories, never in login startup directories.
|
|
324
|
+
They have no KeepAlive/restart policy. A coordinator restart does not restart the
|
|
325
|
+
task. Sleep pauses work; logout and reboot can interrupt it. Never replay a saved
|
|
326
|
+
task automatically. Setup requests identity-verified reload after deliveries drain;
|
|
327
|
+
new LaunchAgent environment/arguments take effect on the next service load.
|
|
328
|
+
Native process/service access may require an ordinary terminal outside an Agent
|
|
329
|
+
tool sandbox. Preserve the original queue/session and inspect any persisted work
|
|
330
|
+
before repeating submission. Desktop socket delivery uses local peer credentials;
|
|
331
|
+
CLI delivery is the fallback when the optional socket is unavailable.
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
launchctl print "gui/$(id -u)/harness-reins"
|
|
335
|
+
tail -f "${REINS_HOME:-$HOME/.reins}/daemon.log"
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## Containers (Docker / AutoDL)
|
|
339
|
+
|
|
340
|
+
Use `--backend screen` where no systemd user manager is available. Install screen
|
|
341
|
+
in the container. Run Reins, the Agent CLI and workload as the same user inside the
|
|
342
|
+
same container with durable local state/workspace mounts. Agent CLI and credentials
|
|
343
|
+
must be available inside that container; the host's desktop socket is not assumed.
|
|
344
|
+
|
|
345
|
+
`reins setup --backend screen --service standalone --now` starts a coordinator in an
|
|
346
|
+
existing AutoDL/container session without systemd. `--service auto` selects systemd
|
|
347
|
+
when reachable, otherwise standalone. Use `--service supervisor` only when explicitly
|
|
348
|
+
managing that configuration. Standalone `--enable` cannot register container startup.
|
|
349
|
+
For Docker images, run `reins daemon` in foreground under `docker --init`, or use an
|
|
350
|
+
external supervisor. A container CMD must not merely spawn a background daemon and exit.
|
|
351
|
+
|
|
352
|
+
When setting up unattended container use, guide the user through the startup route
|
|
353
|
+
appropriate to their platform: a verified AutoDL boot hook invoking standalone
|
|
354
|
+
setup with `--keep-skill --now`, an existing administered Supervisor running
|
|
355
|
+
`reins daemon` with `autostart`/`autorestart`, or a foreground Docker daemon with
|
|
356
|
+
`--restart unless-stopped`. Inspect the actual startup mechanism; creating
|
|
357
|
+
`/root/autodl.sh` alone does not establish that an image executes it. AutoDL elastic
|
|
358
|
+
deployment main commands must stay in the foreground. Preserve existing boot-hook
|
|
359
|
+
commands, Agent profiles, queue paths and service customizations. Pin executable
|
|
360
|
+
paths and runtime environment instead of relying on interactive Conda/NVM setup.
|
|
361
|
+
For custom Supervisor layouts, use its verified configuration with `supervisorctl
|
|
362
|
+
-c`; Reins's built-in installer uses bare control commands and an unscoped update.
|
|
363
|
+
Choose one startup owner per queue and distinguish boot startup from crash recovery.
|
|
364
|
+
Prepare changes within the user's authorized scope; guidance alone does not authorize
|
|
365
|
+
restarting a busy container or replacing platform services. Detailed examples and
|
|
366
|
+
removal steps are in the repository's `docs/containers.md`.
|
|
367
|
+
|
|
368
|
+
After configuration, check the service and `reins doctor` under the same profile, then
|
|
369
|
+
verify startup at a planned idle container restart and a real original-session
|
|
370
|
+
callback/ACK. Report any untested restart behavior explicitly. Coordinator autostart
|
|
371
|
+
does not preserve or authorize replay of an interrupted business process.
|
|
372
|
+
|
|
373
|
+
Terminal disconnection or standalone coordinator exit can leave screen tasks alive
|
|
374
|
+
while the container remains running. If the coordinator is the container's main
|
|
375
|
+
process, its exit ends the container as well. Container stop/recreation interrupts
|
|
376
|
+
work; inspect persisted results/checkpoints and session identity before resubmitting.
|
|
377
|
+
|
|
378
|
+
## Run: submit new work
|
|
379
|
+
|
|
380
|
+
Use this when the agent is launching the long command:
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
reins run \
|
|
384
|
+
--cwd "$PWD" \
|
|
385
|
+
--task "train model" \
|
|
386
|
+
-- python train.py --config configs/exp.yaml
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
The submission is durable before the command returns. Record the printed values. Use the reported log/result paths for either backend. For screen-owned tasks, the
|
|
390
|
+
inspection commands are:
|
|
391
|
+
|
|
392
|
+
```bash
|
|
393
|
+
screen -ls
|
|
394
|
+
screen -r reins-<task-id>
|
|
395
|
+
tail -f ~/.reins/tasks/<task-id>/attempt-1.log
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
Detaching with `Ctrl-a d` leaves the task running.
|
|
399
|
+
|
|
400
|
+
Everything after `--` is one command and its arguments, not shell code. For a sequence, pipes or
|
|
401
|
+
redirection, wrap it: `reins run --task check -- bash -c 'sleep 720; python3 report.py > out.txt'`.
|
|
402
|
+
|
|
403
|
+
Input piped into `reins run`, such as a heredoc script (`reins run --task scan -- python3 - <<'EOF'`),
|
|
404
|
+
is saved with the task and becomes the command's stdin. Without piped input the command's stdin is
|
|
405
|
+
empty, so a command that reads stdin ends instead of waiting for a terminal.
|
|
406
|
+
|
|
407
|
+
## Agent: submit a durable fresh child agent
|
|
408
|
+
|
|
409
|
+
Use `reins agent` when a fresh Codex, Claude Code or Pi process should perform an independent task and
|
|
410
|
+
the work needs independent ownership, durable artifacts, or a completion callback. For short work that
|
|
411
|
+
fits an in-turn native subagent, Reins is unnecessary.
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
reins agent claude --cwd "$PWD" --name parser-review \
|
|
415
|
+
-- "Inspect parser.py and its tests. Report concrete defects and suggested fixes."
|
|
416
|
+
|
|
417
|
+
reins agent codex --cwd "$PWD" --name parser-fix \
|
|
418
|
+
-- "Fix the confirmed parser defects and run the relevant tests."
|
|
419
|
+
|
|
420
|
+
reins agent pi --cwd "$PWD" --name parser-review \
|
|
421
|
+
-- "Inspect parser.py and its tests. Report concrete defects and suggested fixes."
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
### Name, continue and fork child agents
|
|
425
|
+
|
|
426
|
+
Every child agent task is a node with a required short name (`--name`, or an explicit `--task`;
|
|
427
|
+
no `/` or spaces). Reins keeps the child's session, so the same agent can keep working with what it
|
|
428
|
+
already learned. Address a node by its task ID (`1a2b3c4d`), the callback ID you acknowledged
|
|
429
|
+
(`1a2b3c4d-c1`), or its full name (`research/review`); never by a harness session ID. Prefer IDs
|
|
430
|
+
in commands you run: they are short and exact. Names are for showing people what an agent did.
|
|
431
|
+
|
|
432
|
+
```bash
|
|
433
|
+
reins agent codex --name research -- "Survey approaches to X."
|
|
434
|
+
# reins: node research (1a2b3c4d) in context 1a2b3c4d
|
|
435
|
+
reins agent continue 1a2b3c4d --name review -- "Using your survey, review design.md." # research/review
|
|
436
|
+
reins agent fork 1a2b3c4d --name plan -- "Using your survey, draft a plan." # research/plan
|
|
437
|
+
reins context list # ID, name, state and report status of every node
|
|
438
|
+
reins context show 1a2b3c4d-c1 # the chain: each step's task, result and report summary
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
- `continue` appends to the end of a chain and reuses its harness, model and directory. To build
|
|
442
|
+
on an earlier node, `fork` it with a new name; that branch sees exactly what the node knew when it
|
|
443
|
+
finished, not later steps.
|
|
444
|
+
- Wait for a node's callback before continuing or forking it.
|
|
445
|
+
- Read results and report summaries (`reins context show`, the callback, `result.json`). Do not read a
|
|
446
|
+
child's raw session file into your own context; it can be very large.
|
|
447
|
+
|
|
448
|
+
Configured expert agents fix the harness, model, effort and instructions for a kind of task:
|
|
449
|
+
|
|
450
|
+
```bash
|
|
451
|
+
reins expert list # experts in ~/.reins/experts.yaml
|
|
452
|
+
reins agent expert writer --name draft -- "Draft the 0.8 release notes."
|
|
453
|
+
reins expert export > experts.yaml # self-contained; reins expert import on another machine
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
The `codex|claude|pi` subcommand selects the child process. The existing `--agent` option still
|
|
457
|
+
selects the parent agent to wake when explicit callback binding is needed. The text after `--` is
|
|
458
|
+
the child's task, not a shell command. State the objective, relevant paths or context, expected
|
|
459
|
+
deliverable, and real constraints; do not impose a fixed task template when they are unnecessary.
|
|
460
|
+
|
|
461
|
+
Reins snapshots the launching environment and prepares a fresh child environment. For Claude Code,
|
|
462
|
+
use `reins agent claude` instead of manually wrapping `claude -p` with `reins run`: agent mode keeps
|
|
463
|
+
the launching configuration, authentication, proxy, and custom environment while removing parent
|
|
464
|
+
session markers that prevent a clean child launch. Do not put credentials in the task prompt, and
|
|
465
|
+
do not add `--bare` by default.
|
|
466
|
+
|
|
467
|
+
Before the first Claude child, confirm `command -v claude` and `claude auth status`. Do not require
|
|
468
|
+
`ANTHROPIC_API_KEY` specifically: OAuth/keychain and supported cloud providers are valid too. When
|
|
469
|
+
used, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `CLAUDE_CONFIG_DIR`, proxy/certificate settings,
|
|
470
|
+
and other custom values must be available in the submission environment; never print their values.
|
|
471
|
+
|
|
472
|
+
For Pi, use `reins doctor --operation agent --agent-worker pi` to check child readiness.
|
|
473
|
+
`REINS_PI_BIN` overrides the executable. Reins runs
|
|
474
|
+
`pi --print --mode text --session-dir <task dir>/session` with prompt stdin and captures assistant
|
|
475
|
+
text in the managed private result artifact; the session stays in the task directory so the node
|
|
476
|
+
can be continued or forked. Keep the submission-time Pi profile,
|
|
477
|
+
authentication, API, proxy and extension configuration; remove Codex/Claude parent
|
|
478
|
+
markers plus `PI_SESSION_ID`, `PI_SESSION_FILE` and `PI_CODING_AGENT`. Do not put
|
|
479
|
+
credentials in prompts.
|
|
480
|
+
`--model` accepts Pi's model notation, including `provider/model`; `--reasoning-effort`
|
|
481
|
+
maps to `--thinking` and accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
|
|
482
|
+
and `max`, but rejects `ultra`. Tool permissions and project extension trust follow
|
|
483
|
+
Pi's noninteractive configuration; do not add `--approve`. Reins's `--sandbox-mode`
|
|
484
|
+
is Codex-only and `--permission-mode` is Claude-only. Pi 0.87.1's CLI contract was
|
|
485
|
+
checked; native Windows/macOS Pi launch has not been verified in this session.
|
|
486
|
+
|
|
487
|
+
A Pi session can also be a callback parent (`--agent pi`). Pi gets its own installed
|
|
488
|
+
skill for that workflow; from Codex or Claude Code only the `reins agent pi` child applies.
|
|
489
|
+
|
|
490
|
+
Pi accepts `--system-prompt-file ./prompts/pi-system.md` before `--`. Keep this
|
|
491
|
+
separate from `--template`/`--template-file`, which build the stdin task prompt.
|
|
492
|
+
Pi's `--system-prompt` receives the snapshot and replaces its built-in base system
|
|
493
|
+
prompt while retaining normal project context, skills and appended instructions.
|
|
494
|
+
A relative CLI file path uses the submitting shell directory, independently of
|
|
495
|
+
child `--cwd`. Read a nonempty UTF-8 source at submission and snapshot it privately
|
|
496
|
+
as `agent-system-prompt.md`; later edits/deletion must not change queued tasks.
|
|
497
|
+
No interpolation or script evaluation occurs. `--dry-run` reports the resolved
|
|
498
|
+
source without creating task files or starting the child. The flag is Pi-only.
|
|
499
|
+
|
|
500
|
+
Reins owns the private prompt and result files in the managed task directory. The caller does not
|
|
501
|
+
choose those paths. On callback, inspect the child result and relevant artifacts, acknowledge the
|
|
502
|
+
callback, and continue the original goal when the next action is clear.
|
|
503
|
+
|
|
504
|
+
## Done: report externally managed work
|
|
505
|
+
|
|
506
|
+
When editing an existing script, shell trap, Python `finally`, or scheduler epilogue, use:
|
|
507
|
+
|
|
508
|
+
```bash
|
|
509
|
+
set +e
|
|
510
|
+
python train.py --config configs/exp.yaml
|
|
511
|
+
status=$?
|
|
512
|
+
reins done \
|
|
513
|
+
--cwd "$PWD" \
|
|
514
|
+
--task "train model" \
|
|
515
|
+
--command "python train.py --config configs/exp.yaml" \
|
|
516
|
+
--exit-code "$status"
|
|
517
|
+
exit "$status"
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
`done` only queues delivery. It does not make the preceding task durable. Confirm that an external
|
|
521
|
+
process manager already owns that task.
|
|
522
|
+
|
|
523
|
+
Python pattern:
|
|
524
|
+
|
|
525
|
+
```python
|
|
526
|
+
import subprocess
|
|
527
|
+
|
|
528
|
+
status = 1
|
|
529
|
+
try:
|
|
530
|
+
status = subprocess.call(["python", "train.py", "--config", "configs/exp.yaml"])
|
|
531
|
+
finally:
|
|
532
|
+
subprocess.call([
|
|
533
|
+
"reins", "done",
|
|
534
|
+
"--cwd", "/path/to/project",
|
|
535
|
+
"--task", "train model",
|
|
536
|
+
"--command", "python train.py --config configs/exp.yaml",
|
|
537
|
+
"--exit-code", str(status),
|
|
538
|
+
])
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
## Session binding
|
|
542
|
+
|
|
543
|
+
Run from the agent-owned environment and omit target flags by default. Reins detects
|
|
544
|
+
`CODEX_THREAD_ID`, `CLAUDE_CODE_SESSION_ID`, or Pi's absolute `PI_SESSION_FILE` (an ID alone is insufficient).
|
|
545
|
+
|
|
546
|
+
Use `--agent codex|claude|pi --session <id>` when explicit binding is necessary. For Pi,
|
|
547
|
+
prefer the absolute session file from `PI_SESSION_FILE`. If the target cannot be determined, fail
|
|
548
|
+
instead of guessing; there is no "most recent session" fallback.
|
|
549
|
+
|
|
550
|
+
## Restart recovery
|
|
551
|
+
|
|
552
|
+
### Daemon restart
|
|
553
|
+
|
|
554
|
+
For native tasks, the independent systemd unit, launchd job or Windows scheduled
|
|
555
|
+
runner owns the worker. Restarting the
|
|
556
|
+
coordinator should not restart that task. If querying the owner fails, its state
|
|
557
|
+
is unknown; never treat a manager connection failure as permission to relaunch.
|
|
558
|
+
A saved result takes precedence over owner visibility. Reconstruct a missing
|
|
559
|
+
callback with the same ID. Old screen records use their original recovery path.
|
|
560
|
+
|
|
561
|
+
### Worker startup handshake
|
|
562
|
+
|
|
563
|
+
For the legacy screen backend, a launched worker must durably move its task from `launching` to `running`. Allow a
|
|
564
|
+
one-second handshake window. If screen disappears first, record the failed launch and retry no
|
|
565
|
+
more than three total attempts with exponential backoff. After the final failure, set
|
|
566
|
+
`launch_failed`, remove the launch credentials, queue exactly one recovery callback, and never
|
|
567
|
+
automatically relaunch that task. Generate worker tokens with a `reins_` prefix and pass them only
|
|
568
|
+
as a single `--token=value` argument. Treat a legacy `launching` record without an attempt counter
|
|
569
|
+
as an unknown prior launch failure and never automatically retry it during upgrade.
|
|
570
|
+
|
|
571
|
+
Native systemd/launchd/Windows launches with ambiguous outcomes are not retried automatically,
|
|
572
|
+
even if no unit is visible. Inspect the task record and outputs.
|
|
573
|
+
|
|
574
|
+
### Same-host reboot
|
|
575
|
+
|
|
576
|
+
No backend preserves the running process across a host reboot. Never automatically rerun the command and do not add a
|
|
577
|
+
`--resume-command` mechanism. Restore the originally bound Codex or Claude Code conversation with
|
|
578
|
+
the task id, screen name, log path, interruption reason, and available checkpoint/artifact context.
|
|
579
|
+
|
|
580
|
+
The restored agent must:
|
|
581
|
+
|
|
582
|
+
1. inspect local logs, outputs, processes, manifests, and checkpoints;
|
|
583
|
+
2. supplement the completed status if durable artifacts prove completion;
|
|
584
|
+
3. otherwise recreate the task through the normal `reins run` workflow from a valid
|
|
585
|
+
checkpoint;
|
|
586
|
+
4. or record the exact blocking condition.
|
|
587
|
+
|
|
588
|
+
### Cross-host recovery
|
|
589
|
+
|
|
590
|
+
Do not attempt it. Reins does not transfer code, data, environments, checkpoints, credentials, or
|
|
591
|
+
compute resources between hosts.
|
|
592
|
+
|
|
593
|
+
## Callback acknowledgement
|
|
594
|
+
|
|
595
|
+
The callback prompt includes:
|
|
596
|
+
|
|
597
|
+
```bash
|
|
598
|
+
reins ack [--queue-dir <queue-dir>] <callback-id>
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
After inspecting the result and choosing whether to continue, stop, or ask, run that command.
|
|
602
|
+
Acknowledgements are monotonic. Missing ACKs retry with backoff. Delivery is at-least-once, so
|
|
603
|
+
always inspect existing processes and artifacts before starting follow-up work.
|
|
604
|
+
An ACK marker immediately ends completion-stream waiting and releases the delivery lease; it must
|
|
605
|
+
not wait for a separate Desktop App Server `turn/completed` notification.
|
|
606
|
+
The resumed agent needs write access only to the callback queue. A normal ACK must not create or
|
|
607
|
+
modify global target-lock files; if a rare retained lease needs cleanup, the daemon reconciles it
|
|
608
|
+
after the durable ACK marker appears.
|
|
609
|
+
|
|
610
|
+
Use `--callback-format full` at submission only when full inline detail is needed.
|
|
611
|
+
The default compact format archives the complete original callback privately and
|
|
612
|
+
omits recurring counter explanations. System/user reminder cadence remains 4/3;
|
|
613
|
+
user-hook text is preserved on its scheduled callbacks.
|
|
614
|
+
|
|
615
|
+
Callback ACK confirms one delivery only. It must never implicitly complete a persistent goal.
|
|
616
|
+
|
|
617
|
+
## Goal acknowledgement and automatic inquiry
|
|
618
|
+
|
|
619
|
+
Every multi-stage goal must use a mutable UTF-8 YAML goal plan. Treat that file as the single
|
|
620
|
+
source of truth for the current overall goal and its ordered path, not the task text remembered
|
|
621
|
+
from an earlier turn. Use this schema:
|
|
622
|
+
|
|
623
|
+
```yaml
|
|
624
|
+
version: 1
|
|
625
|
+
revision: 1
|
|
626
|
+
goal: Release version 0.6.2
|
|
627
|
+
path:
|
|
628
|
+
- id: implement
|
|
629
|
+
title: Implement the change
|
|
630
|
+
status: completed
|
|
631
|
+
evidence: tests/test_feature.py
|
|
632
|
+
- id: verify
|
|
633
|
+
title: Run tests and inspect the result
|
|
634
|
+
status: in_progress
|
|
635
|
+
- id: publish
|
|
636
|
+
title: Publish the release
|
|
637
|
+
status: pending
|
|
638
|
+
amendments:
|
|
639
|
+
- revision: 1
|
|
640
|
+
reason: Initial path
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
Statuses are `pending`, `in_progress`, `blocked`, and `completed`. Completed items must form a
|
|
644
|
+
continuous prefix of `path`; there may be at most one `in_progress` or `blocked` item, and it must
|
|
645
|
+
be the first unfinished item.
|
|
646
|
+
|
|
647
|
+
The plan is intentionally editable. The user or agent may revise later path items, reopen an
|
|
648
|
+
earlier item, append or remove items, or change the overall `goal`. Increment `revision` and record
|
|
649
|
+
the reason in `amendments` when the intended path changes. After each item, update its status and
|
|
650
|
+
evidence. Always follow the latest valid file; do not preserve an obsolete path from memory.
|
|
651
|
+
|
|
652
|
+
Workflow:
|
|
653
|
+
|
|
654
|
+
1. Create it once:
|
|
655
|
+
|
|
656
|
+
```bash
|
|
657
|
+
reins goal start --id <goal-id> --session <session-id> --cwd "$PWD" \
|
|
658
|
+
--task "..." --plan-file path/to/goal-plan.yaml
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
2. Bind each `run` or `done` callback with `--goal-id <goal-id>`.
|
|
662
|
+
3. Before saying or implying that the whole goal is complete, check the latest plan:
|
|
663
|
+
|
|
664
|
+
```bash
|
|
665
|
+
reins goal check --id <goal-id>
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
Inspect the actual work and artifacts against every path item. This command reports the
|
|
669
|
+
current item, remaining path, and the current plan SHA-256.
|
|
670
|
+
4. Only if every item, including the final item, is confirmed `completed`:
|
|
671
|
+
|
|
672
|
+
```bash
|
|
673
|
+
reins goal ack --id <goal-id> --state completed --plan-sha256 <checked-sha256>
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
5. If progress requires a specific missing condition:
|
|
677
|
+
|
|
678
|
+
```bash
|
|
679
|
+
reins goal ack --id <goal-id> --state blocked_conditions \
|
|
680
|
+
--condition "specific prerequisite"
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
6. When that condition is met:
|
|
684
|
+
|
|
685
|
+
```bash
|
|
686
|
+
reins goal resume --id <goal-id>
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
The completion gate rejects an unchecked plan, a stale digest, an invalid/nonsequential path, or
|
|
690
|
+
any unfinished item. Editing the YAML invalidates an earlier check, so the agent must reread the
|
|
691
|
+
new overall goal and path. Completion is terminal. A callback ACK does not count as goal
|
|
692
|
+
completion.
|
|
693
|
+
|
|
694
|
+
For an active goal created before YAML plans were required, or to move a plan file, attach the
|
|
695
|
+
latest plan and then check it again:
|
|
696
|
+
|
|
697
|
+
```bash
|
|
698
|
+
reins goal set-plan --id <goal-id> --plan-file path/to/goal-plan.yaml
|
|
699
|
+
reins goal check --id <goal-id>
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
### Plan file lifecycle and user agreement
|
|
703
|
+
|
|
704
|
+
- Use one plan file for one independent goal. Prefer a stable project-local path such as
|
|
705
|
+
`.reins/goals/<goal-id>.yaml`. Never recycle a completed goal's file for another goal.
|
|
706
|
+
- Before `goal start`, derive the overall goal, acceptance conditions, and ordered path from the
|
|
707
|
+
user's request, then create the YAML. For a clear, conventional, low-risk path, create it and
|
|
708
|
+
tell the user its location and main items without waiting for another approval. If the path
|
|
709
|
+
requires a strategic choice, materially different resource use, changed acceptance criteria,
|
|
710
|
+
or another consequential tradeoff, agree on those points with the user before starting.
|
|
711
|
+
- Keep using the same file when the goal is blocked, resumed, or revised. The user may edit it at
|
|
712
|
+
any time; their latest valid revision overrides the agent's remembered path. A follow-on
|
|
713
|
+
objective after terminal completion is a new goal with a new file.
|
|
714
|
+
- After completion, preserve the YAML at its recorded path as the audit record. Do not delete it
|
|
715
|
+
automatically. If the user wants it under an archive directory, move it while the goal is still
|
|
716
|
+
active, run `goal set-plan` with the archive path, and then perform the final `goal check` and
|
|
717
|
+
completion ACK.
|
|
718
|
+
|
|
719
|
+
After three hours without a newly queued ordinary callback, the daemon automatically restores the
|
|
720
|
+
same conversation and asks it to continue, ACK completion, or state the exact blocking condition.
|
|
721
|
+
The inquiry repeats until the goal is completed or blocked. Reboot recovery callbacks follow the
|
|
722
|
+
same goal rules and do not disable this inquiry.
|
|
723
|
+
|
|
724
|
+
## Multi-round behavior
|
|
725
|
+
|
|
726
|
+
After each wakeup, inspect relevant logs, metrics, checkpoints, reports, and outputs. Decide:
|
|
727
|
+
|
|
728
|
+
```text
|
|
729
|
+
current_goal:
|
|
730
|
+
last_result:
|
|
731
|
+
decision: continue | stop_success | stop_blocked | ask_user
|
|
732
|
+
reason:
|
|
733
|
+
next_command:
|
|
734
|
+
budget_remaining:
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
Continue only when the next action is clear, low-risk, aligned with the same goal, and within the
|
|
738
|
+
user's budget and project rules. Ask before expanding resource use, changing the scientific or
|
|
739
|
+
product objective, deleting artifacts, or making a strategic tradeoff.
|
|
740
|
+
|
|
741
|
+
When stopping, summarize what was attempted, what changed, and the smallest decision or resource
|
|
742
|
+
needed from the user.
|
|
743
|
+
|
|
744
|
+
## Daemon operations
|
|
745
|
+
|
|
746
|
+
The systemd user service (Linux), LaunchAgent (macOS), or login scheduled task
|
|
747
|
+
(Windows) keeps `reins daemon` available
|
|
748
|
+
for submissions, recovery, and callbacks. On Linux:
|
|
749
|
+
|
|
750
|
+
```bash
|
|
751
|
+
systemctl --user status harness-reins.service
|
|
752
|
+
journalctl --user -u harness-reins.service -f
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
The daemon watches `${REINS_HOME:-~/.reins}/queue` by default. Use `--queue-dir`
|
|
756
|
+
or `REINS_QUEUE_DIR` for an explicit queue.
|
|
757
|
+
|
|
758
|
+
Before restarting a service or container, drain live callback deliveries where possible.
|
|
759
|
+
Unacknowledged interrupted delivery is eligible for replay.
|
|
760
|
+
|
|
761
|
+
Cancel callbacks through the CLI rather than deleting state:
|
|
762
|
+
|
|
763
|
+
```bash
|
|
764
|
+
reins cancel --id <callback-id>
|
|
765
|
+
reins cancel --queue-dir <queue-dir> --all --message "no longer needed"
|
|
766
|
+
```
|
|
767
|
+
|
|
768
|
+
`cancel` cancels callbacks only; it does not terminate a running workload.
|
|
769
|
+
|
|
770
|
+
## Independent test authoring preset
|
|
771
|
+
|
|
772
|
+
Use `reins agent codex --template test --task "write independent tests" -- "Requirements and specification paths"`
|
|
773
|
+
when a separate agent should author tests for the parent to execute. The default Codex model is
|
|
774
|
+
`gpt-5.6-luna` with `max` reasoning; override using `--model` and `--reasoning-effort`.
|
|
775
|
+
These flags affect the child only; `--agent` continues to select the parent callback agent.
|
|
776
|
+
Claude supports the template and `--model`, inherits its own model by default, and rejects
|
|
777
|
+
`--reasoning-effort`. Pi supports the same prompt and handoff, inherits its own model/thinking
|
|
778
|
+
configuration unless overridden, and accepts the thinking levels listed above. The built-in
|
|
779
|
+
Codex model/effort defaults never apply to Pi. Put all flags before `--`; provide concrete requirements after it.
|
|
780
|
+
|
|
781
|
+
The child writes requirement-derived tests and a handoff, without running tests or modifying
|
|
782
|
+
production code. The parent reviews the changed files, requirements and commands, then runs
|
|
783
|
+
the tests and reports actual results. Child completion is not a passing-test result. Diagnose
|
|
784
|
+
failed/empty/partial handoffs before execution; never weaken assertions merely to get green.
|
|
785
|
+
The shared workspace is not isolated: these are prompt constraints, so inspect actual changes.
|
|
786
|
+
Use `--dry-run` to inspect the expanded prompt and resolved model before submission.
|
|
787
|
+
|
|
788
|
+
## User-defined child templates
|
|
789
|
+
|
|
790
|
+
Load `--template NAME` from `${REINS_TEMPLATE_DIR}` when set, otherwise
|
|
791
|
+
`${XDG_CONFIG_HOME:-~/.config}/reins/templates/NAME.yaml` (or `.yml`), or use
|
|
792
|
+
`--template-file PATH` for an explicit file. These options are mutually exclusive.
|
|
793
|
+
A relative file path uses the submitting shell directory, not the child's `--cwd`.
|
|
794
|
+
Template names/filename stems start with a letter or digit and otherwise use only
|
|
795
|
+
letters, digits, underscores and hyphens. No reinstall is needed when files change.
|
|
796
|
+
|
|
797
|
+
YAML requires `version: 1` (positive integer revision) and non-empty `prompt: |` text.
|
|
798
|
+
Optional `codex: {model: gpt-5.6-luna, reasoning_effort: max}` and
|
|
799
|
+
`claude: {model: sonnet}` set worker-specific defaults; Pi also accepts
|
|
800
|
+
`pi: {model: provider/id, reasoning_effort: high}`. CLI options take precedence.
|
|
801
|
+
Optional `pi: {system_prompt_file: prompts/system.md}` loads a separate nonempty
|
|
802
|
+
UTF-8 system prompt; its relative path uses the YAML directory. An explicit
|
|
803
|
+
`--system-prompt-file` overrides it and resolves relative to the submitting shell.
|
|
804
|
+
Optional `handoff: |` text instructs the parent on callback. No variable interpolation
|
|
805
|
+
or code evaluation occurs. Unknown/duplicate fields or invalid values fail before
|
|
806
|
+
submission. Use `--dry-run` to inspect source, prompt, defaults and handoff.
|
|
807
|
+
|
|
808
|
+
A same-named user template replaces the entire built-in profile, including its
|
|
809
|
+
callback guidance; a custom `test` must supply its own test handoff instructions.
|
|
810
|
+
Do not silently fall back from a malformed user file to the built-in. Both `.yaml`
|
|
811
|
+
and `.yml` existing for one name is an error. Submission freezes source, revision,
|
|
812
|
+
prompt, model/effort and handoff, so edits do not alter queued work.
|