docs(inference_optimizer): detach the optimizer the way the harness understands

[zoroyihan7]

The launch recipe says setsid nohup ... &, and gives the reason: a harness's own background shell can die on SSH disconnect. That reason is sound and the form is right where it applies. It is wrong under Claw, and the way it is wrong is not visible from inside the run.

Claw deletes a sandbox once lastActivity + 15m passes. lastActivity only moves for traffic the platform can see, and it stops pinging the moment the agent turn reaches a terminal state, on the rule that a finished turn leaves behind at most a warm cache. A setsid nohup optimizer is invisible to all of that — it holds nothing open, it is registered nowhere, and a sandbox busy with it looks exactly like an abandoned one.

On 2026-09-02 four dispatches lost a live sandbox to this. The cleanest reported task.completed at 10:43:14 and lost its pod at 10:57:46 — no error in between, the optimiser still working. Reproduced deliberately on 2026-09-03: a turn that started a background job finished at 07:42:56, the keepalive stopped in the same second while the job still had four minutes to run, and the control plane deleted the sandbox at 07:57:56, fifteen minutes and one second after the last activity.

So the recipe branches on the harness. Where it applies, the command goes to the bash tool with run_in_background=true, which detaches it just as thoroughly but through the door the platform can see. Everywhere else setsid nohup ... & is unchanged.

The branch takes two conditions, not one

$CLAW_SESSION_ID set and the bash tool takes a run_in_background parameter. Both, or setsid nohup stays correct.

Each answers half the question, and each was found the hard way:

• The session id alone was unreachable. Claw set it on the sandbox but never passed it to the shell a command runs in, so the test could never be true and every agent following the rule fell through to setsid nohup — the exact failure this PR exists to prevent. Fixed in Let a command see the session it is running for, and retire the alias that stood in for it PrimusClaw#51, which has landed; the test now answers.
• The parameter alone is wrong in the other direction. Agent harnesses off-platform have background modes of their own. Keying only on "does my tool offer it" points a local run at one of those, which regresses precisely what setsid is there for: nothing off-platform reclaims a sandbox, and such a shell may not outlive the connection that started it. Local mode must keep setsid nohup, and with both conditions it does.

Four cases, all correct: on-platform with background shells on → the tool; on-platform with them off → setsid, since the tool offers no parameter; local with an agent harness → setsid, since the session id is unset; local bare shell → setsid.

Three things follow

• $PID_FILE comes from the launch-info JSON's .pid on both paths. The tool returns a shell_id and never a pid, and $! under setsid is the wrapper, which exits immediately — the robustness monitor reads that file and fires a spurious resume on a dead pid. operations.md already said to reconcile it; the two documents now agree on where the number comes from.

• The health check stops asking /proc. A zombie keeps its /proc entry and sandbox PID 1 does not reap — 18 of 56 processes were zombies in a sandbox sampled while writing this — so test -d /proc/$pid reports a dead optimiser as alive for as long as the pod survives. It asks ps for the state and rejects Z.

• The robustness monitor is detached by the same rule. It outlives the turn on purpose, so it had the same problem the optimiser did.

Every document that taught the old form is updated together — both packaged docs, the example skills, and the pre-release prompts — because one left behind is one an agent will follow. The second commit covers five sites that never carried the branch at all, including the pre-release resume nudge, which is injected at runtime and told an agent to use setsid nohup unconditionally at the exact moment the rule matters most.

Verification

Docs only — no Python touched. The tests that parse these files pass (133), including test_pre_release_stall_liveness, which asserts the literal setsid nohup still appears in the two demo prompts.

Verified end to end on a cluster carrying the PrimusClaw fix, with a real GPU workload: an agent given no hint about detaching read the skill, checked both conditions, and launched a 30-minute optimizer run with run_in_background=true. The job outlived the agent turn, ran to its budget and exited cleanly; the platform held the sandbox while it ran and reclaimed it shortly after it finished. The run manifest also recorded a real claw_session_id for the first time, the same PrimusClaw fix making both work.

[github-actions]

CI E2E report — ✅ Succeeded

item	value
result	✅ Succeeded
model	Qwen/Qwen3-0.6B (dense)
resources	1× GPU, TP=1
PR branch	fix/optimizer-launch-via-claw-background-shell
commit	6152cf41cd9988cf5fa6e49e97634ecd7318f798
session_id	b54840ce-290c-4742-85e5-fb90c3c38eaf
queue → dispatch	4m 30s
run time	170m 42s
total	175m 12s

details