@harness-reins/linux-x64 0.0.0-stage → 0.9.0

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 +140 -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.0.dist-info/INSTALLER +1 -0
  16. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/METADATA +13 -0
  17. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/RECORD +199 -0
  18. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/REQUESTED +0 -0
  19. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/WHEEL +5 -0
  20. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/direct_url.json +1 -0
  21. package/dist/reins/_internal/harness_reins-0.9.0.dist-info/entry_points.txt +3 -0
  22. package/dist/reins/_internal/harness_reins-0.9.0.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 @@
1
+ fe8eb0450082
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: harness-reins
3
+ description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this turn, and get woken in this same Claude Code session when they finish via a background `reins wait`. Use instead of sleeping, polling logs, or leaving a job owned by the Bash tool whenever a command may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
4
+ ---
5
+
6
+ # Harness Reins for Claude Code
7
+
8
+ Reins hands a long command to an independent OS task owner (launchd on macOS, systemd on Linux,
9
+ Task Scheduler on Windows) and queues a callback when it exits. In Claude Code you receive that
10
+ callback **in this live session** by running `reins wait` as a background Bash command: Claude Code
11
+ wakes you when a background command exits, and `reins wait` exits as soon as the callback is ready.
12
+
13
+ The full reference (all flags, platforms, recovery and goals) is in [REFERENCE.md](REFERENCE.md).
14
+ Read it only when you need details beyond this page. It is shared with other agents; where it
15
+ differs from this page about callback delivery, this page applies to Claude Code.
16
+
17
+ ## When to use it
18
+
19
+ - Reliably done within 60 seconds → run it in the foreground once. No Reins.
20
+ - About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
21
+ - Never keep a job alive by polling it with `sleep`/`tail`, and never leave a long job owned by a
22
+ `run_in_background` Bash shell: it dies with the session and is not recovered.
23
+
24
+ ## The workflow
25
+
26
+ 1. **Submit** (foreground; returns in a second or two):
27
+
28
+ ```bash
29
+ reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
30
+ ```
31
+
32
+ stderr prints the task id, backend, log path, and a ready-made line:
33
+ `reins: Claude Code live callback: run in the background (run_in_background): .../reins wait --queue-dir ... --task <id>`
34
+
35
+ If it instead says the callback `arrives through the reins channel`, this session was started with
36
+ `reins claude`: skip step 2. The callback is pushed into this session as a
37
+ `<channel source="reins">` event; handle it as in step 3.
38
+
39
+ 2. **Wait** — run exactly that `reins wait ... --task <id>` command with the Bash tool's
40
+ `run_in_background: true`. Do not run it in the foreground (it blocks until the job ends), and do
41
+ not poll its output. Then tell the user what is running and end your turn, or carry on with other
42
+ work.
43
+
44
+ If the Bash tool has no `run_in_background` (background tasks are disabled; `reins run` then says
45
+ so instead of printing a wait command), skip the wait: tell the user what is running and end your
46
+ turn. When the job finishes, Reins resumes this session headlessly and the callback arrives as the
47
+ next message.
48
+
49
+ 3. **Wake up** — when the job finishes, the background command exits and prints a callback:
50
+
51
+ ```text
52
+ [reins] <task-id>-c1
53
+ Task: train model
54
+ Result: exited 0 · 2h 3m 32s
55
+ From: run on systemd-user
56
+ Files: <task dir>/ (attempt-1.log)
57
+ Details: <path> (as needed | read before acting)
58
+ Session: <this session id> (only)
59
+ ACK after inspection: reins ack <task-id>-c1
60
+ ```
61
+
62
+ Read the background command's output, inspect the log and artifacts (read Details first when it
63
+ says "read before acting"), decide `continue | stop_success | stop_blocked | ask_user`, then run
64
+ the `reins ack ...` command from the callback. ACK means "received and inspected", not "goal done".
65
+ An exit code is process status, not proof that tests passed.
66
+
67
+ 4. **Next step** — if you launch follow-up work, submit it with `reins run` again and start a new
68
+ background `reins wait --task <new-id>`. Inspect existing processes and outputs first: delivery is
69
+ at-least-once.
70
+
71
+ ## Other entry points
72
+
73
+ - **Fresh child agent** (independent review, test authoring, a parallel fix):
74
+
75
+ ```bash
76
+ reins agent claude --cwd "$PWD" --name parser-review -- "Inspect parser.py and report concrete defects."
77
+ reins agent codex --template test --name parser-tests -- "Test the contract in docs/parser.md."
78
+ reins agent continue <task-or-callback-id> --name recheck -- "I fixed those; review parser.py again."
79
+ ```
80
+
81
+ Every child needs `--name`. `reins agent continue <id>` reuses the same child with what it already
82
+ learned; `reins agent fork <id>` branches from it. `<id>` is the task ID, the callback ID, or the
83
+ node's full name; prefer IDs. See `reins context show <node>` for summaries;
84
+ never read a child's raw session.
85
+
86
+ Then background `reins wait --task <id>` exactly as for `reins run`. The child's result path is in the
87
+ callback. A Claude child needs a standalone `claude` CLI that is signed in (`claude auth status`);
88
+ the Claude desktop app's bundled CLI cannot authenticate on its own.
89
+
90
+ - **Work already owned elsewhere** (tmux, screen, Slurm, a script): add `reins done` at its end.
91
+
92
+ ```bash
93
+ set +e; python train.py; status=$?
94
+ reins done --cwd "$PWD" --task "train model" --command "python train.py" --exit-code "$status"
95
+ exit "$status"
96
+ ```
97
+
98
+ The callback id is not known in advance, so start a background `reins wait` with no `--task`: it
99
+ delivers the next unacknowledged callback bound to this session.
100
+
101
+ ## Rules
102
+
103
+ - **After `--` comes one command, not shell code**: for `;`, `&&`, pipes or redirection use
104
+ `-- bash -c '...'` (`reins run --task check -- bash -c 'sleep 720; python3 report.py'`).
105
+ - **Heredoc scripts work**: input piped into `reins run` (`-- python3 - <<'EOF'`) becomes the task's
106
+ stdin. Without piped input the task's stdin is empty.
107
+ - **Session binding is automatic** from `CLAUDE_CODE_SESSION_ID`. Never invent a session id. `reins wait` refuses to run without a session.
108
+ - **One wait, one wake-up.** A wait exits after printing what it found; start a new one for the next
109
+ task. Every unacknowledged callback of this session keeps coming back until you ACK it.
110
+ - **If the session closes**, nothing is lost: when no waiter is alive, the Reins daemon falls back to a
111
+ headless `claude -p --resume <session>` from the session's original directory. That fallback needs
112
+ a signed-in standalone CLI; otherwise the callback stays queued and the next `reins wait` from this
113
+ session (or `reins status`) picks it up. After a live delivery, the daemon waits 30 minutes for the
114
+ ACK before it falls back.
115
+ - `reins wait` exists only for Claude Code. It refuses to run without `CLAUDE_CODE_SESSION_ID` and
116
+ never touches callbacks bound to other agents.
117
+ - **Do not** call `claude -p --resume` yourself, add `--via-daemon`, or invent launch flags. Callback
118
+ problems never change the task's own exit code unless the user asks for `--strict`.
119
+ - **Long objectives with several stages**: use `reins goal start|check|ack` with a YAML plan file, see
120
+ REFERENCE.md ("Goal acknowledgement"). Callback ACK never completes a goal.
121
+
122
+ ## `[reins-status]` blocks
123
+
124
+ If `reins run`, `reins agent` or `reins done` prints JSON between `[reins-status]` and `[/reins-status]`, it is
125
+ addressed to you: fix the listed configuration issues yourself (do not hand routine setup back to the
126
+ user), run its `recheck_command`, then continue. Check `work.state` first — `task_persisted` or
127
+ `callback_queued` means the work already exists: repair around that id and **do not submit it again**.
128
+ For an explicit check: `reins doctor --agent claude --session "$CLAUDE_CODE_SESSION_ID"`.
129
+
130
+ ## Install and verify
131
+
132
+ ```bash
133
+ python3 -m pip install "git+https://github.com/lz59970062/harness-reins.git"
134
+ reins setup --force --enable --now
135
+ reins doctor --agent claude --session "$CLAUDE_CODE_SESSION_ID"
136
+ ```
137
+
138
+ Useful commands: `reins status` (unacknowledged callbacks), `reins cancel --id <id>`,
139
+ `reins retry --id <id>` (re-deliver a result without rerunning the task),
140
+ `tail -f <task log>` when the user asks to watch progress.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: harness-reins
3
+ description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this turn, then end the turn; Reins starts a new turn in this same Codex thread with the result. Use instead of sleeping, polling logs, waiting on a running exec session, or blocking a tool call whenever a command or a wait for time to pass may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
4
+ ---
5
+
6
+ # Harness Reins for Codex
7
+
8
+ Reins hands a long command to an independent OS task owner (systemd on Linux, launchd on macOS,
9
+ Task Scheduler on Windows; `screen` as fallback) and queues a callback when it exits. When this
10
+ thread is idle, Reins delivers the callback **as a new turn in this same thread**: `codex exec
11
+ resume` for CLI sessions, the shared App Server for Codex Desktop. You do not wait for it; you end
12
+ your turn and the result comes back to you.
13
+
14
+ The full reference (all flags, platforms, Desktop modes, recovery and goals) is in
15
+ [REFERENCE.md](REFERENCE.md). Read it only when you need details beyond this page; where it
16
+ differs from this page about callback delivery, this page applies to Codex.
17
+
18
+ Reins resumes this thread with the permissions recorded when you submit (`workspace-write`,
19
+ `on-request` by default). If this session runs without a sandbox (for example
20
+ `--dangerously-bypass-approvals-and-sandbox` in a container), submit with
21
+ `--sandbox-mode danger-full-access --approval-policy never` (or have `REINS_SANDBOX_MODE` and
22
+ `REINS_APPROVAL_POLICY` set) so the resumed turn can still run commands and ACK.
23
+
24
+ ## When to use it
25
+
26
+ - Reliably done within 60 seconds → run it in the foreground once. No Reins.
27
+ - About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
28
+ - Waiting for time to pass (a real-time clock, a schedule, a cooldown) is a long job too: submit the
29
+ wait, `reins run --cwd "$PWD" --task "wait for hour 12" -- sleep 900`.
30
+ - Never wait inside this turn: no `sleep` longer than about a minute, no loops of `sleep` plus a
31
+ status or log check, no long `yield_time_ms` or repeated empty `write_stdin` on a running exec
32
+ session, no `tail -f`/`tail --pid`, and no `reins wait` (that is for Claude Code background
33
+ commands). Never start long jobs with `&`, `nohup` or `setsid`: Reins owns them.
34
+
35
+ ## The workflow
36
+
37
+ 1. **Submit** (returns in a second or two):
38
+
39
+ ```bash
40
+ reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
41
+ ```
42
+
43
+ Inside Codex, Reins binds the callback to this thread through `$CODEX_THREAD_ID`. stderr prints
44
+ the task id, backend and log path. The command after `--` is argv, not shell code: use
45
+ `-- bash -c '...'` for pipes, `&&` or redirection.
46
+
47
+ 2. **End your turn.** Do any independent work first, then finish with a short message saying what
48
+ is running and what you will do with the result. In `codex exec` this exits Codex; Reins resumes
49
+ this thread when the task ends. Submitting several tasks before ending the turn is fine: each
50
+ arrives as its own callback.
51
+
52
+ 3. **Handle the callback** — it arrives as the user message of a new turn:
53
+
54
+ ```text
55
+ [reins] <task-id>-c1
56
+ Task: train model
57
+ Result: exited 0 · 2h 3m 32s
58
+ From: run on systemd-user
59
+ Files: <task dir>/ (attempt-1.log)
60
+ Details: <path> (as needed | read before acting)
61
+ Session: <this thread> (only)
62
+ ACK after inspection: reins ack <task-id>-c1
63
+ ```
64
+
65
+ Inspect the log and artifacts (read Details first when it says "read before acting"), decide
66
+ `continue | stop_success | stop_blocked | ask_user`, then run the `reins ack ...` command from
67
+ the callback. ACK means "received and inspected", not "goal done". An exit code is process
68
+ status, not proof that tests passed. Delivery is at-least-once: check existing processes and
69
+ outputs before relaunching anything. ACK **every** callback. If more work is needed, submit it
70
+ with `reins run` and end the turn again.
71
+
72
+ 4. **Stop a task early** by killing its process (`pkill -f '<its command>'`); `reins cancel` cancels
73
+ only the callback, not the workload. The callback still arrives with the exit status; ACK it.
74
+
75
+ ## Other entry points
76
+
77
+ - `reins agent codex|claude|pi --cwd "$PWD" --name <name> -- "<prompt>"` — a child agent; its result
78
+ comes back as a callback here. `reins agent continue <node>` or `fork <node>` reuses what that child
79
+ learned; `reins context show <node>` gives summaries (never read its raw session).
80
+ - `reins done --cwd "$PWD" --task "..." --exit-code 0` — report work you are already supervising.
81
+ - `reins status --state pending --state running` — inspect tasks and callbacks once; do not poll it.
82
+
83
+ ## `[reins-status]` blocks
84
+
85
+ Reins prints an `[reins-status]` JSON block when something needs attention. You own the repair: follow
86
+ `repair_command`, then `recheck_command`. `callback_queued` or `task_persisted` means the work
87
+ already exists — repair delivery around that id and **do not submit it again**. Do not run
88
+ `codex exec resume` yourself from a tool call; Reins owns delivery.
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: harness-reins
3
+ description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this run, and get the result steered back into this same Pi session when they finish. Use instead of sleeping, polling logs, or blocking a tool call whenever a command or a wait for time to pass may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
4
+ ---
5
+
6
+ # Harness Reins for Pi
7
+
8
+ Reins hands a long command to an independent OS task owner (systemd on Linux, launchd on macOS,
9
+ Task Scheduler on Windows; `screen` as fallback) and queues a callback when it exits. Reins's Pi
10
+ extension delivers that callback **into this live Pi process** through Pi's native steering:
11
+ while you are busy it arrives after the current tool batch, before your next model call; while
12
+ idle it starts a normal turn. You do not need to wait, poll, or end your run to receive it.
13
+
14
+ The full reference (all flags, platforms, recovery and goals) is in [REFERENCE.md](REFERENCE.md).
15
+ Read it only when you need details beyond this page. It is shared with other agents; where it
16
+ differs from this page about callback delivery, this page applies to Pi.
17
+
18
+ ## When to use it
19
+
20
+ - Reliably done within 60 seconds → run it in the foreground once. No Reins.
21
+ - About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
22
+ - Waiting for time to pass (a real-time clock, a schedule, a cooldown) is a long job too: submit the
23
+ wait, `reins run --cwd "$PWD" --task "wait for hour 12" -- sleep 900`, instead of `sleep 900` in a
24
+ tool call. Pi's shell has no time limit, so a long foreground `sleep` will not fail; it blocks
25
+ you and every callback steered to you until it returns.
26
+ - Never `sleep` longer than about a minute in a tool call, never loop `sleep` + status/log checks,
27
+ and never start long jobs with `&`, `nohup` or `setsid`: Reins owns them and tells you when they end.
28
+
29
+ ## The workflow
30
+
31
+ 1. **Submit** (returns in a second or two):
32
+
33
+ ```bash
34
+ reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
35
+ ```
36
+
37
+ Inside Pi's shell, Reins binds the callback to this session's absolute `$PI_SESSION_FILE`
38
+ automatically. stderr prints the task id, backend and log path.
39
+
40
+ 2. **Keep working** on independent work, or tell the user what is running and stop. There is
41
+ nothing to wait on: the callback is pushed to you. Do not poll the task: one look at its log to
42
+ check early progress is fine, but do not wait in a tool call for it to change. With several tasks
43
+ running, each finished one arrives as its own callback. In print mode (`pi -p`) a managed session
44
+ (`reins pi`) exits when you stop and Reins resumes it with the callback, so ending your answer is the
45
+ right way to wait.
46
+
47
+ 3. **Handle the callback** — it arrives as a user message:
48
+
49
+ ```text
50
+ [reins] <task-id>-c1
51
+ Task: train model
52
+ Result: exited 0 · 2h 3m 32s
53
+ From: run on systemd-user
54
+ Files: <task dir>/ (attempt-1.log)
55
+ Details: <path> (as needed | read before acting)
56
+ Session: <this session file> (only)
57
+ ACK after inspection: reins ack <task-id>-c1
58
+ ```
59
+
60
+ Inspect the log and artifacts (read Details first when it says "read before acting"), decide
61
+ `continue | stop_success | stop_blocked | ask_user`, then run the `reins ack ...` command from
62
+ the callback. ACK means "received and inspected", not "goal done". An exit code is process
63
+ status, not proof that tests passed. Delivery is at-least-once: check existing processes and
64
+ outputs before relaunching anything.
65
+
66
+ ACK **every** callback, including ones that arrive back to back while you handle another. A
67
+ callback that names "Earlier callbacks ... never ACKed" lists ids you missed: inspect each and
68
+ run its `reins ack`.
69
+
70
+ 4. **Stop a task early** by killing its process (`pkill -f '<its command>'`); `reins cancel` cancels
71
+ only the callback, not the workload. The callback still arrives with the exit status; ACK it.
72
+
73
+ ## Ordinary and managed Pi sessions
74
+
75
+ - **Ordinary Pi** (started as `pi`, with the extension installed) receives callbacks only while
76
+ it is running. If this process exits before ACKing a delivered callback, Reins marks it for manual
77
+ recovery instead of replaying it; when Pi was closed before delivery, reopen the session and run
78
+ `reins retry --id <callback-id>`.
79
+ - **Managed Pi** (`reins pi --cwd "$PWD"` or `reins pi --session /absolute/session.jsonl`) locks the
80
+ session file for its lifetime. After it fully exits, Reins may deliver a pending callback by
81
+ resuming the same file in print mode. Managed sessions are pinned: restart `reins pi` to switch,
82
+ fork or reload.
83
+
84
+ ## Other entry points
85
+
86
+ - `reins agent codex|claude|pi --cwd "$PWD" --name <name> -- "<prompt>"` — a child agent; its result
87
+ comes back as a callback here. `reins agent continue <node>` or `fork <node>` reuses what that child
88
+ learned; `reins context show <node>` gives summaries (never read its raw session).
89
+ - `reins done --cwd "$PWD" --task "..." --exit-code 0` — report work you are already supervising.
90
+ - `reins status --state pending --state running` — inspect tasks and callbacks.
91
+
92
+ ## `[reins-status]` blocks
93
+
94
+ Reins prints an `[reins-status]` JSON block when something needs attention. You own the repair: follow
95
+ `repair_command`, then `recheck_command`. `callback_queued` or `task_persisted` means the work
96
+ already exists — repair delivery around that id and **do not submit it again**. For Pi, a blocked
97
+ route usually means the extension is not loaded: `reins install-pi-extension`, then `/reload` (or
98
+ restart Pi), then recheck with `reins doctor --agent pi --session "$PI_SESSION_FILE"`.