@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.
Files changed (77) hide show
  1. package/dist/reins/_internal/base_library.zip +0 -0
  2. package/dist/reins/_internal/harness_reins/_build.txt +1 -0
  3. package/dist/reins/_internal/harness_reins/assets/skills/claude/SKILL.md +144 -0
  4. package/dist/reins/_internal/harness_reins/assets/skills/codex/SKILL.md +88 -0
  5. package/dist/reins/_internal/harness_reins/assets/skills/pi/SKILL.md +98 -0
  6. package/dist/reins/_internal/harness_reins/assets/skills/reference/SKILL.md +812 -0
  7. package/dist/reins/_internal/harness_reins/assets/skills/reference/agents/openai.yaml +4 -0
  8. package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/desktop-package-launch.py +263 -0
  9. package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/invoke-desktop-package.ps1 +14 -0
  10. package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/probe-desktop-launch.py +217 -0
  11. package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/start-desktop-bridge.ps1 +449 -0
  12. package/dist/reins/_internal/harness_reins/harness/pi/extension/reins-callback.js +272 -0
  13. package/dist/reins/_internal/harness_reins/owners/windows_scheduler.ps1 +156 -0
  14. package/dist/reins/_internal/harness_reins/templates/test.md +38 -0
  15. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/INSTALLER +1 -0
  16. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/METADATA +18 -0
  17. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/RECORD +199 -0
  18. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/REQUESTED +0 -0
  19. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/WHEEL +5 -0
  20. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/direct_url.json +1 -0
  21. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/entry_points.txt +3 -0
  22. package/dist/reins/_internal/harness_reins-0.9.2.dist-info/top_level.txt +1 -0
  23. package/dist/reins/_internal/lib-dynload/_bisect.cpython-312-x86_64-linux-gnu.so +0 -0
  24. package/dist/reins/_internal/lib-dynload/_blake2.cpython-312-x86_64-linux-gnu.so +0 -0
  25. package/dist/reins/_internal/lib-dynload/_bz2.cpython-312-x86_64-linux-gnu.so +0 -0
  26. package/dist/reins/_internal/lib-dynload/_codecs_cn.cpython-312-x86_64-linux-gnu.so +0 -0
  27. package/dist/reins/_internal/lib-dynload/_codecs_hk.cpython-312-x86_64-linux-gnu.so +0 -0
  28. package/dist/reins/_internal/lib-dynload/_codecs_iso2022.cpython-312-x86_64-linux-gnu.so +0 -0
  29. package/dist/reins/_internal/lib-dynload/_codecs_jp.cpython-312-x86_64-linux-gnu.so +0 -0
  30. package/dist/reins/_internal/lib-dynload/_codecs_kr.cpython-312-x86_64-linux-gnu.so +0 -0
  31. package/dist/reins/_internal/lib-dynload/_codecs_tw.cpython-312-x86_64-linux-gnu.so +0 -0
  32. package/dist/reins/_internal/lib-dynload/_contextvars.cpython-312-x86_64-linux-gnu.so +0 -0
  33. package/dist/reins/_internal/lib-dynload/_csv.cpython-312-x86_64-linux-gnu.so +0 -0
  34. package/dist/reins/_internal/lib-dynload/_ctypes.cpython-312-x86_64-linux-gnu.so +0 -0
  35. package/dist/reins/_internal/lib-dynload/_datetime.cpython-312-x86_64-linux-gnu.so +0 -0
  36. package/dist/reins/_internal/lib-dynload/_decimal.cpython-312-x86_64-linux-gnu.so +0 -0
  37. package/dist/reins/_internal/lib-dynload/_hashlib.cpython-312-x86_64-linux-gnu.so +0 -0
  38. package/dist/reins/_internal/lib-dynload/_heapq.cpython-312-x86_64-linux-gnu.so +0 -0
  39. package/dist/reins/_internal/lib-dynload/_json.cpython-312-x86_64-linux-gnu.so +0 -0
  40. package/dist/reins/_internal/lib-dynload/_lzma.cpython-312-x86_64-linux-gnu.so +0 -0
  41. package/dist/reins/_internal/lib-dynload/_md5.cpython-312-x86_64-linux-gnu.so +0 -0
  42. package/dist/reins/_internal/lib-dynload/_multibytecodec.cpython-312-x86_64-linux-gnu.so +0 -0
  43. package/dist/reins/_internal/lib-dynload/_opcode.cpython-312-x86_64-linux-gnu.so +0 -0
  44. package/dist/reins/_internal/lib-dynload/_pickle.cpython-312-x86_64-linux-gnu.so +0 -0
  45. package/dist/reins/_internal/lib-dynload/_posixsubprocess.cpython-312-x86_64-linux-gnu.so +0 -0
  46. package/dist/reins/_internal/lib-dynload/_random.cpython-312-x86_64-linux-gnu.so +0 -0
  47. package/dist/reins/_internal/lib-dynload/_sha1.cpython-312-x86_64-linux-gnu.so +0 -0
  48. package/dist/reins/_internal/lib-dynload/_sha2.cpython-312-x86_64-linux-gnu.so +0 -0
  49. package/dist/reins/_internal/lib-dynload/_sha3.cpython-312-x86_64-linux-gnu.so +0 -0
  50. package/dist/reins/_internal/lib-dynload/_socket.cpython-312-x86_64-linux-gnu.so +0 -0
  51. package/dist/reins/_internal/lib-dynload/_ssl.cpython-312-x86_64-linux-gnu.so +0 -0
  52. package/dist/reins/_internal/lib-dynload/_statistics.cpython-312-x86_64-linux-gnu.so +0 -0
  53. package/dist/reins/_internal/lib-dynload/_struct.cpython-312-x86_64-linux-gnu.so +0 -0
  54. package/dist/reins/_internal/lib-dynload/_uuid.cpython-312-x86_64-linux-gnu.so +0 -0
  55. package/dist/reins/_internal/lib-dynload/array.cpython-312-x86_64-linux-gnu.so +0 -0
  56. package/dist/reins/_internal/lib-dynload/binascii.cpython-312-x86_64-linux-gnu.so +0 -0
  57. package/dist/reins/_internal/lib-dynload/fcntl.cpython-312-x86_64-linux-gnu.so +0 -0
  58. package/dist/reins/_internal/lib-dynload/grp.cpython-312-x86_64-linux-gnu.so +0 -0
  59. package/dist/reins/_internal/lib-dynload/math.cpython-312-x86_64-linux-gnu.so +0 -0
  60. package/dist/reins/_internal/lib-dynload/pyexpat.cpython-312-x86_64-linux-gnu.so +0 -0
  61. package/dist/reins/_internal/lib-dynload/resource.cpython-312-x86_64-linux-gnu.so +0 -0
  62. package/dist/reins/_internal/lib-dynload/select.cpython-312-x86_64-linux-gnu.so +0 -0
  63. package/dist/reins/_internal/lib-dynload/termios.cpython-312-x86_64-linux-gnu.so +0 -0
  64. package/dist/reins/_internal/lib-dynload/unicodedata.cpython-312-x86_64-linux-gnu.so +0 -0
  65. package/dist/reins/_internal/lib-dynload/zlib.cpython-312-x86_64-linux-gnu.so +0 -0
  66. package/dist/reins/_internal/libbz2.so.1.0 +0 -0
  67. package/dist/reins/_internal/libcrypto.so.1.1 +0 -0
  68. package/dist/reins/_internal/libffi.so.7 +0 -0
  69. package/dist/reins/_internal/liblzma.so.5 +0 -0
  70. package/dist/reins/_internal/libpython3.12.so.1.0 +0 -0
  71. package/dist/reins/_internal/libssl.so.1.1 +0 -0
  72. package/dist/reins/_internal/libuuid.so.1 +0 -0
  73. package/dist/reins/_internal/libz.so.1 +0 -0
  74. package/dist/reins/_internal/yaml/_yaml.cpython-312-x86_64-linux-gnu.so +0 -0
  75. package/dist/reins/reins +0 -0
  76. package/package.json +14 -4
  77. 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.