[F5] `nous stop --immediate` to halt SDK turn at next event boundary, not phase boundary

[sriumcp]

Problem

nous stop writes a STOP sentinel that's honored only at phase boundaries (DESIGN→GATE, GATE→EXECUTE_ANALYZE, etc.). If a user issues nous stop mid-EXECUTE_ANALYZE while the agent is building wrong code, STOP does not fire until the entire EXECUTE_ANALYZE phase completes — potentially 30+ minutes of further wrong-direction work.

In the paper-memorytime-mirage campaign this forced the user to pkill -TERM the resume process directly to halt promptly, bypassing nous's clean shutdown.

Desired behavior

A new nous stop --immediate <work_dir> mode that signals the executor SDK turn to abort cleanly at the next event boundary (e.g., between SDK turns, or on the next tool-call return), rather than the next phase boundary.

The SDK already has a "turn observed >600s silence" abort path. Extending it to also check for "STOP-immediate sentinel detected" at the same checkpoints would be analogous and keep the abort mechanism unified.

Suggested implementation sketch

1. Define a second sentinel filename (e.g., STOP_IMMEDIATE) alongside the existing STOP sentinel in the work_dir.
2. In the SDK turn loop (likely orchestrator/sdk_dispatch.py or similar), at each tool-call return, check for STOP_IMMEDIATE. If present, abort the turn cleanly with a status code that nous can detect and route to a graceful shutdown.
3. Add a nous stop --immediate <work_dir> CLI flag that writes both sentinels (so a normal-stop fallback is preserved if the SDK turn ignores immediate).
4. Document the difference: STOP halts at phase boundary; STOP_IMMEDIATE halts at next SDK event boundary.

Acceptance criteria

• nous stop --immediate <work_dir> writes the immediate-stop sentinel.
• The SDK turn loop checks for the sentinel at each tool-call boundary and aborts cleanly when set.
• After abort, the work_dir is in a state that nous resume can pick up from.
• Documentation distinguishes phase-boundary STOP vs event-boundary STOP_IMMEDIATE.
• Friction report F5 row in the tracking issue checks off.

Severity

LOW-MEDIUM — workaround (pkill) exists but is jarring and bypasses cleanup paths.

Source

friction-report.md F5, paper-memorytime-mirage campaign (2026-05).

---

Part of friction-report tracking issue #245.