duet-cli 0.2.10__tar.gz → 0.2.12__tar.gz

{duet_cli-0.2.10/duet_cli.egg-info → duet_cli-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: duet-cli
-Version: 0.2.10
+Version: 0.2.12
 Summary: Two CLI agents in conversation. One Python file. Stdlib only.
 Author: Volkan Altan
 License-Expression: MIT
@@ -235,9 +235,19 @@ stop, duet opens a `force>` prompt so you can push another round.
 Every run writes a directory with `transcript.md`, `state.json`, per-turn
 stderr logs, and the `wt/` worktree when `--worktree` is on. Inspect a run with
 `duet --status <run-id> --json` (or omit `--json` for the human view), list runs
-with `duet --list`, and start a fresh run
+with `duet --list`, stop one exact live run with `duet --stop <run-id>`, and
+start a fresh run
 from saved state with `duet --continue <run> --task "next thing"`.
 
+`--stop` is graceful. It lets the current agent turn finish before duet records
+`force_stop`. Use `--stop <run-id> --immediate` to terminate that run's active
+child and record `force_stop` now. Both forms validate the saved supervisor PID
+and process-start identity. They never use a process-name match or signal a
+different duet run.
+
+If status remains `awaiting_force`, press Enter in the original terminal.
+Some platforms do not wake the blocking `force>` input after an external signal.
+
 - **Backends:** `claude`, `codex`, `gemini`, `copilot`, `opencode`
 - **Roles:** `planner`, `coder`, `reviewer`, `triage-reviewer`, or a custom one
 - **Reasoning:** `--reasoning minimal|low|medium|high|xhigh|max`
@@ -254,7 +264,7 @@ a deep-reasoning turn is stuck.
 
 [docs/USAGE.md](https://github.com/volkan/duet/blob/main/docs/USAGE.md) is the
 full reference: every flag, reasoning levels, session memory, output layout,
-`--status` / `--continue`, the force prompt, Codex sandbox and network rules,
+`--status` / `--stop` / `--continue`, the force prompt, Codex sandbox and network rules,
 and worktree mode.
 
 ## Contributing

{duet_cli-0.2.10 → duet_cli-0.2.12}/README.md

@@ -214,9 +214,19 @@ stop, duet opens a `force>` prompt so you can push another round.
 Every run writes a directory with `transcript.md`, `state.json`, per-turn
 stderr logs, and the `wt/` worktree when `--worktree` is on. Inspect a run with
 `duet --status <run-id> --json` (or omit `--json` for the human view), list runs
-with `duet --list`, and start a fresh run
+with `duet --list`, stop one exact live run with `duet --stop <run-id>`, and
+start a fresh run
 from saved state with `duet --continue <run> --task "next thing"`.
 
+`--stop` is graceful. It lets the current agent turn finish before duet records
+`force_stop`. Use `--stop <run-id> --immediate` to terminate that run's active
+child and record `force_stop` now. Both forms validate the saved supervisor PID
+and process-start identity. They never use a process-name match or signal a
+different duet run.
+
+If status remains `awaiting_force`, press Enter in the original terminal.
+Some platforms do not wake the blocking `force>` input after an external signal.
+
 - **Backends:** `claude`, `codex`, `gemini`, `copilot`, `opencode`
 - **Roles:** `planner`, `coder`, `reviewer`, `triage-reviewer`, or a custom one
 - **Reasoning:** `--reasoning minimal|low|medium|high|xhigh|max`
@@ -233,7 +243,7 @@ a deep-reasoning turn is stuck.
 
 [docs/USAGE.md](https://github.com/volkan/duet/blob/main/docs/USAGE.md) is the
 full reference: every flag, reasoning levels, session memory, output layout,
-`--status` / `--continue`, the force prompt, Codex sandbox and network rules,
+`--status` / `--stop` / `--continue`, the force prompt, Codex sandbox and network rules,
 and worktree mode.
 
 ## Contributing

{duet_cli-0.2.10 → duet_cli-0.2.12}/duet.py

@@ -63,7 +63,7 @@ from typing import Callable, Iterable, Optional
 
 # ---------- defaults ----------
 
-__version__ = "0.2.10"
+__version__ = "0.2.12"
 
 DEFAULT_SENTINEL = "<<<LGTM>>>"
 DEFAULT_SANDBOX = "workspace-write"
@@ -120,6 +120,8 @@ STATUS_PHASES = {
     "finished",
     "unknown",
 }
+STOP_GRACEFUL_SIGNAL = getattr(signal, "SIGUSR1", None)
+STOP_IMMEDIATE_SIGNAL = signal.SIGTERM
 
 
 class AgentRunError(RuntimeError):
@@ -272,16 +274,17 @@ CLAUDE_REASONING_MAP = {
 }
 
 # Codex CLI takes a config override `-c model_reasoning_effort=<value>`.
-# Its accepted values, lowest→highest, are: minimal, low, medium, high, xhigh.
-# We also map duet's `max` alias to Codex's `xhigh` because Codex does not
-# document a separate `max` effort value.
+# Pass every duet level through unchanged. Codex support is model-specific, so
+# its model resolver must reject an unsupported value instead of duet silently
+# changing the requested effort. Always emit an explicit requested value: a
+# model's native default is not necessarily `medium`.
 CODEX_REASONING_MAP = {
     "minimal": "minimal",
     "low":     "low",
     "medium":  "medium",
     "high":    "high",
     "xhigh":   "xhigh",
-    "max":     "xhigh",
+    "max":     "max",
 }
 
 # Gemini CLI does not expose a documented reasoning-effort flag. Keep the duet
@@ -618,7 +621,8 @@ class VerifyResult:
 # ---------- active child process tracking ----------
 
 _ACTIVE_PROCS: set[subprocess.Popen] = set()
-_ACTIVE_PROCS_LOCK = threading.Lock()
+# A signal handler can interrupt the main thread inside this lock and re-enter it.
+_ACTIVE_PROCS_LOCK = threading.RLock()
 
 
 def _register_proc(proc: subprocess.Popen) -> None:
@@ -1421,10 +1425,7 @@ def call_codex(agent: Agent, system_prompt: str, message: str,
     reasoning_args: list[str] = []
     if effective:
         codex_value = backend_adapter("codex").reasoning_map.get(effective, effective)
-        # `medium` is Codex's default; only override when we actually want a
-        # different effort level.
-        if codex_value != "medium":
-            reasoning_args = ["-c", f"model_reasoning_effort={codex_value}"]
+        reasoning_args = ["-c", f"model_reasoning_effort={codex_value}"]
     if fast:
         # Concise reasoning summaries cut output volume and time-to-first-token
         # on Codex turns. Pairs with low effort above; together they're the
@@ -2092,6 +2093,41 @@ def _install_sigint(stop: StopFlag) -> None:
     signal.signal(signal.SIGINT, handler)
 
 
+def _install_run_stop_signal(stop: StopFlag) -> None:
+    """Handle repeatable graceful stop requests without changing Ctrl-C."""
+    if STOP_GRACEFUL_SIGNAL is None:
+        return
+
+    def handler(signum, frame):
+        if not stop.requested:
+            print(
+                "\n[duet] graceful stop requested — finishing the current "
+                "turn, then stopping.",
+                file=sys.stderr,
+            )
+        stop.request("run_stop")
+
+    signal.signal(STOP_GRACEFUL_SIGNAL, handler)
+
+
+def _install_sigterm(stop: StopFlag) -> None:
+    """Make run-scoped immediate stops durable before this process exits."""
+    def handler(signum, frame):
+        if not stop.requested:
+            print(
+                "\n[duet] immediate stop requested — terminating the active "
+                "child, then stopping.",
+                file=sys.stderr,
+            )
+        stop.request("SIGTERM")
+        # Each tracked child is its own process-group leader. This preserves
+        # the existing descendant cleanup without signaling the supervisor's
+        # process group or any other duet run.
+        _terminate_active_processes(signal.SIGKILL)
+
+    signal.signal(signal.SIGTERM, handler)
+
+
 def _convergence_markers(text: str, sentinel: str) -> tuple[bool, bool]:
     """Return (sentinel_seen, rationale_seen), ignoring fenced code blocks."""
     sentinel_re = re.compile(rf"^\s*{re.escape(sentinel)}\s*$")
@@ -2424,6 +2460,7 @@ def _build_run_state(cfg: DuetConfig, *, turns_used: int, history: list,
         "codex_fast": cfg.codex_fast,
         "continue_from": cfg.continue_from,
         "duet_pid": os.getpid(),
+        "duet_process_start": _CURRENT_PROCESS_START_IDENTITY,
         "error": error,
     }
     if cfg.recap:
@@ -2486,6 +2523,34 @@ def _launch_failure_state(
     return state
 
 
+def _requested_stop_state(
+    cfg: DuetConfig,
+    *,
+    history: list,
+    transcript_path: pathlib.Path,
+    recap_path: pathlib.Path,
+    state_path: pathlib.Path,
+    wt_path: Optional[pathlib.Path] = None,
+    wt_branch: Optional[str] = None,
+) -> dict:
+    """Persist an intentional stop that interrupted a setup subprocess."""
+    state = _build_run_state(
+        cfg,
+        turns_used=len(history),
+        history=history,
+        finished_reason=FINISHED_FORCE_STOP,
+        transcript_path=transcript_path,
+        recap_path=recap_path,
+        wt_path=wt_path,
+        wt_branch=wt_branch,
+    )
+    _write_run_state(state_path, state)
+    print(f"[duet] done. reason=force_stop. transcript: {transcript_path}")
+    if cfg.recap:
+        print(f"[duet] recap: {recap_path}")
+    return state
+
+
 def _run_kickoff_command(
     cfg: DuetConfig,
     *,
@@ -2496,6 +2561,7 @@ def _run_kickoff_command(
     history: list,
     wt_path: Optional[pathlib.Path],
     wt_branch: Optional[str],
+    stop: StopFlag,
     log: Callable[..., None],
 ) -> Optional[dict]:
     """Execute deferred task_from_cmd; return terminal state on failure."""
@@ -2519,6 +2585,17 @@ def _run_kickoff_command(
             cfg.task_from_cmd, cfg.cwd, cfg.per_turn_timeout, run_dir
         )
     except Exception as exc:
+        if stop.requested and stop.reason == "SIGTERM":
+            log("duet", "stop", "[duet] immediate stop requested", kind="stop")
+            return _requested_stop_state(
+                cfg,
+                history=history,
+                transcript_path=transcript_path,
+                recap_path=recap_path,
+                state_path=state_path,
+                wt_path=wt_path,
+                wt_branch=wt_branch,
+            )
         message = str(exc)
         summary = _error_summary(message, type(exc).__name__)
         log(
@@ -2797,6 +2874,7 @@ def _derive_seed_or_failure(
     cfg: DuetConfig, *, run_dir: pathlib.Path, transcript_path: pathlib.Path,
     recap_path: pathlib.Path, state_path: pathlib.Path, history: list,
     wt_path: Optional[pathlib.Path], wt_branch: Optional[str],
+    stop: StopFlag,
     log: Callable[..., None],
 ) -> tuple[Optional[str], Optional[dict]]:
     """Extract the opening seed message from the lead agent.
@@ -2826,6 +2904,18 @@ def _derive_seed_or_failure(
             )
         return derive_seed(cfg, run_dir=run_dir), None
     except Exception as e:
+        if stop.requested and stop.reason == "SIGTERM":
+            log("duet", "stop", "[duet] immediate stop requested", kind="stop")
+            state = _requested_stop_state(
+                cfg,
+                history=history,
+                transcript_path=transcript_path,
+                recap_path=recap_path,
+                state_path=state_path,
+                wt_path=wt_path,
+                wt_branch=wt_branch,
+            )
+            return None, state
         failure_reason = _agent_finished_reason(e)
         seed_agent = cfg.agents[0]
         reply = _agent_failure_block(
@@ -2921,6 +3011,8 @@ def _prepare_run(cfg: DuetConfig) -> tuple[_RunContext, Optional[dict]]:
 
     stop = StopFlag()
     _install_sigint(stop)
+    _install_run_stop_signal(stop)
+    _install_sigterm(stop)
     history: list[dict] = []
     transcript = ""
 
@@ -2963,7 +3055,7 @@ def _prepare_run(cfg: DuetConfig) -> tuple[_RunContext, Optional[dict]]:
     failure = _run_kickoff_command(
         cfg, run_dir=run_dir, transcript_path=transcript_path,
         recap_path=recap_path, state_path=state_path, history=history,
-        wt_path=None, wt_branch=None, log=log,
+        wt_path=None, wt_branch=None, stop=stop, log=log,
     )
     if failure is not None:
         return context, failure
@@ -2978,6 +3070,16 @@ def _prepare_run(cfg: DuetConfig) -> tuple[_RunContext, Optional[dict]]:
             cfg, run_id, run_dir
         )
     except RunSetupError as exc:
+        if stop.requested and stop.reason == "SIGTERM":
+            log("duet", "stop", "[duet] immediate stop requested", kind="stop")
+            state = _requested_stop_state(
+                cfg,
+                history=history,
+                transcript_path=transcript_path,
+                recap_path=recap_path,
+                state_path=state_path,
+            )
+            return context, state
         state = _launch_failure_state(
             cfg, reason=FINISHED_SETUP_ERROR, message=str(exc), history=history,
             transcript_path=transcript_path, recap_path=recap_path,
@@ -3026,7 +3128,7 @@ def run_duet(cfg: DuetConfig) -> dict:
     seed, seed_failure_state = _derive_seed_or_failure(
         cfg, run_dir=run_dir, transcript_path=transcript_path,
         recap_path=recap_path, state_path=state_path, history=history,
-        wt_path=wt_path, wt_branch=wt_branch, log=log,
+        wt_path=wt_path, wt_branch=wt_branch, stop=stop, log=log,
     )
     if seed_failure_state is not None:
         return seed_failure_state
@@ -3063,6 +3165,9 @@ def run_duet(cfg: DuetConfig) -> dict:
         else:
             print(result.reply)
 
+        if stop.requested and stop.reason == "SIGTERM":
+            finished_reason = FINISHED_FORCE_STOP
+            break
         if result.failure_reason is not None:
             if _continue_after_timeout(result, may_continue, stop):
                 print(f"[duet] turn {turn:02d} ({speaker.name}) timed out after "
@@ -3076,14 +3181,13 @@ def run_duet(cfg: DuetConfig) -> dict:
                 continue
             finished_reason = result.failure_reason
             break
+        if stop.requested:
+            finished_reason = FINISHED_FORCE_STOP
+            break
         previous_turn_timed_out = False
         if result.convergence_hit and previous_convergence_proposal:
             finished_reason = FINISHED_CONVERGED
             break
-        if stop.requested:
-            finished_reason = FINISHED_FORCE_STOP
-            break
-
         last_msg = result.reply
         previous_convergence_proposal = result.convergence_hit
         speaker_idx = 1 - speaker_idx
@@ -3095,7 +3199,7 @@ def run_duet(cfg: DuetConfig) -> dict:
         finished_reason, forced_verify_state = ask_force(
             cfg, history, transcript_path, state_path,
             last_msg, speaker_idx, seen_first_turn,
-            finished_reason, wt_path, wt_branch
+            finished_reason, wt_path, wt_branch, stop=stop,
         )
     if forced_verify_state is not None:
         last_verify_state = forced_verify_state
@@ -3227,8 +3331,11 @@ def ask_force(cfg: DuetConfig, history: list, transcript_path: pathlib.Path,
               state_path: pathlib.Path, last_msg: str, speaker_idx: int,
               seen_first_turn: dict, reason: str,
               wt_path: Optional[pathlib.Path] = None,
-              wt_branch: Optional[str] = None) -> tuple[str, Optional[dict]]:
+              wt_branch: Optional[str] = None,
+              stop: Optional[StopFlag] = None) -> tuple[str, Optional[dict]]:
     """Post-loop interactive prompt: human can push another turn or accept."""
+    if stop is not None and stop.requested:
+        return FINISHED_FORCE_STOP, None
     if not sys.stdin.isatty():
         return reason, None
     last_verify_state: Optional[dict] = None
@@ -3253,7 +3360,12 @@ def ask_force(cfg: DuetConfig, history: list, transcript_path: pathlib.Path,
         try:
             line = input("force> ").strip()
         except EOFError:
-            return reason, last_verify_state
+            return (
+                FINISHED_FORCE_STOP if stop is not None and stop.requested else reason,
+                last_verify_state,
+            )
+        if stop is not None and stop.requested:
+            return FINISHED_FORCE_STOP, last_verify_state
         if not line:
             return reason, last_verify_state
         next_speaker = cfg.agents[speaker_idx]
@@ -3274,21 +3386,24 @@ def ask_force(cfg: DuetConfig, history: list, transcript_path: pathlib.Path,
             last_verify_state=last_verify_state,
         )
         last_verify_state = result.last_verify_state
+        forced_reason = result.failure_reason
+        if stop is not None and stop.requested:
+            forced_reason = FINISHED_FORCE_STOP
         # Persist each forced turn so a crash at the next force> prompt doesn't
         # lose it (the --status/--continue durability contract). finished_reason
         # stays None mid-loop (duet is alive at the prompt); run_duet writes the
         # final state with the real reason once ask_force returns.
         forced_state = _build_run_state(
             cfg, turns_used=len(history), history=history,
-            finished_reason=result.failure_reason,
+            finished_reason=forced_reason,
             transcript_path=transcript_path,
             recap_path=transcript_path.parent / "recap.md",
             last_verify=last_verify_state, wt_path=wt_path, wt_branch=wt_branch,
             phase="awaiting_force",
         )
         _write_run_state(state_path, forced_state)
-        if result.failure_reason is not None:
-            return result.failure_reason, last_verify_state
+        if forced_reason is not None:
+            return forced_reason, last_verify_state
         last_msg = result.reply
         speaker_idx = 1 - speaker_idx
         reason = FINISHED_FORCED_CONTINUATION
@@ -3797,16 +3912,8 @@ def _proc_cmdline(pid: int) -> Optional[str]:
     return None
 
 
-def _is_duet_process(pid: int) -> bool:
-    """True if `pid` is alive AND looks like a duet.py process (avoids stale-PID false positives)."""
-    if not _pid_alive(pid):
-        return False
-    cmdline = _proc_cmdline(pid)
-    if cmdline is None:
-        # Sandboxed macOS callers may be allowed to probe a sibling PID with
-        # signal 0 but denied `ps`. PID 1 is never duet; for other live PIDs,
-        # liveness is the best evidence available when identity is hidden.
-        return pid != 1
+def _looks_like_duet_cmdline(cmdline: str) -> bool:
+    """Return whether a command line identifies a duet entry point."""
     try:
         argv = shlex.split(cmdline)
     except ValueError:
@@ -3824,6 +3931,90 @@ def _is_duet_process(pid: int) -> bool:
     return False
 
 
+def _proc_start_identity(pid: int) -> Optional[str]:
+    """Return the strongest stable process-start identity available."""
+    if sys.platform.startswith("linux"):
+        try:
+            stat = pathlib.Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+            # The command name is parenthesized and can contain spaces. Fields
+            # after its final ')' start at procfs field 3; starttime is field 22.
+            fields = stat[stat.rfind(")") + 2:].split()
+            return f"linux-proc-start:{fields[19]}"
+        except (OSError, IndexError):
+            return None
+    if sys.platform == "darwin":
+        try:
+            import ctypes
+
+            class ProcBsdInfo(ctypes.Structure):
+                _fields_ = [
+                    ("flags", ctypes.c_uint32),
+                    ("status", ctypes.c_uint32),
+                    ("xstatus", ctypes.c_uint32),
+                    ("pid", ctypes.c_uint32),
+                    ("ppid", ctypes.c_uint32),
+                    ("uid", ctypes.c_uint32),
+                    ("gid", ctypes.c_uint32),
+                    ("ruid", ctypes.c_uint32),
+                    ("rgid", ctypes.c_uint32),
+                    ("svuid", ctypes.c_uint32),
+                    ("svgid", ctypes.c_uint32),
+                    ("rfu", ctypes.c_uint32),
+                    ("comm", ctypes.c_char * 16),
+                    ("name", ctypes.c_char * 32),
+                    ("nfiles", ctypes.c_uint32),
+                    ("pgid", ctypes.c_uint32),
+                    ("pjobc", ctypes.c_uint32),
+                    ("e_tdev", ctypes.c_uint32),
+                    ("e_tpgid", ctypes.c_uint32),
+                    ("nice", ctypes.c_int32),
+                    ("start_sec", ctypes.c_uint64),
+                    ("start_usec", ctypes.c_uint64),
+                ]
+
+            info = ProcBsdInfo()
+            libproc = ctypes.CDLL("/usr/lib/libproc.dylib")
+            size = ctypes.sizeof(info)
+            read = libproc.proc_pidinfo(
+                pid, 3, 0, ctypes.byref(info), size  # PROC_PIDTBSDINFO
+            )
+            if read == size and info.pid == pid and info.start_sec:
+                return f"darwin-proc-start:{info.start_sec}:{info.start_usec}"
+        except (AttributeError, OSError, TypeError, ValueError):
+            pass
+    try:
+        result = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=2,
+        )
+        started = " ".join(result.stdout.split())
+        if result.returncode == 0 and started:
+            return f"ps-lstart:{started}"
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+    return None
+
+
+_CURRENT_PROCESS_START_IDENTITY = _proc_start_identity(os.getpid())
+
+
+def _is_duet_process(pid: int) -> bool:
+    """True if `pid` is alive AND looks like a duet.py process."""
+    if not _pid_alive(pid):
+        return False
+    cmdline = _proc_cmdline(pid)
+    if cmdline is None:
+        # Status is observational. A sandbox can hide identity inspection, so
+        # retain its prior liveness fallback. Mutating stop operations use the
+        # stricter proof in `_validated_stop_target` instead.
+        return pid != 1
+    return _looks_like_duet_cmdline(cmdline)
+
+
 def _utc_rfc3339(value: float) -> str:
     timestamp = dt.datetime.fromtimestamp(value, tz=dt.timezone.utc)
     return timestamp.isoformat(timespec="seconds").replace("+00:00", "Z")
@@ -4243,6 +4434,141 @@ def _resolve_run_dir(arg: str, *, warn_ambiguous: bool = True) -> Optional[pathl
     return None
 
 
+def _bare_stop_run_candidates(arg: str) -> list[pathlib.Path]:
+    """Return distinct directories addressed by one bare run id."""
+    if "/" in arg or "\\" in arg or not _RUN_ID_RE.match(arg):
+        return []
+    candidates = [pathlib.Path(arg), *(
+        root / arg for root in _default_list_paths()
+    )]
+    unique: list[pathlib.Path] = []
+    seen: set[pathlib.Path] = set()
+    for candidate in candidates:
+        if not candidate.is_dir():
+            continue
+        try:
+            resolved = candidate.resolve()
+        except OSError:
+            continue
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        unique.append(resolved)
+    return unique
+
+
+class StopTargetError(RuntimeError):
+    """A run cannot be safely resolved or proven before signaling."""
+
+    def __init__(self, message: str, exit_code: int) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def _read_stop_state(run_dir: pathlib.Path) -> dict:
+    state_path = run_dir / "state.json"
+    if not state_path.is_file():
+        raise StopTargetError(f"missing state.json in {run_dir}", 3)
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise StopTargetError(
+            f"cannot read state.json in {run_dir}: {type(exc).__name__}", 3
+        ) from exc
+    if not isinstance(state, dict):
+        raise StopTargetError(f"state.json root is not an object in {run_dir}", 3)
+    return state
+
+
+def _validated_stop_target(arg: str) -> tuple[pathlib.Path, int]:
+    """Resolve a run and prove its exact live supervisor identity.
+
+    Unlike status, this mutating path never falls back from hidden process
+    identity to liveness alone. It also binds the PID to the process-start
+    identity saved by that supervisor, which detects PID reuse.
+    """
+    bare_candidates = _bare_stop_run_candidates(arg)
+    if len(bare_candidates) > 1:
+        raise StopTargetError(
+            f"run id {arg!r} is ambiguous across multiple roots; "
+            "pass an explicit run directory path",
+            2,
+        )
+    run_dir = bare_candidates[0] if bare_candidates else _resolve_run_dir(arg)
+    if run_dir is None:
+        raise StopTargetError(f"run directory not found: {arg}", 3)
+    state = _read_stop_state(run_dir)
+    if state.get("finished_reason") is not None or state.get("phase") == "finished":
+        raise StopTargetError(f"run is already terminal: {run_dir}", 2)
+
+    pid = _coerce_pid(state.get("duet_pid"))
+    if pid is None:
+        raise StopTargetError(f"run has an invalid duet_pid: {run_dir}", 2)
+    if pid == 1:
+        raise StopTargetError("refusing to signal PID 1", 2)
+    if not _pid_alive(pid):
+        raise StopTargetError(f"duet supervisor PID {pid} is stale", 2)
+
+    saved_start = state.get("duet_process_start")
+    if not isinstance(saved_start, str) or not saved_start:
+        raise StopTargetError(
+            "run lacks a saved supervisor start identity; refusing unsafe stop", 2
+        )
+    live_start = _proc_start_identity(pid)
+    if live_start is None:
+        raise StopTargetError(
+            f"cannot prove the start identity of duet supervisor PID {pid}", 2
+        )
+    if live_start != saved_start:
+        raise StopTargetError(
+            f"duet supervisor PID {pid} was reused; refusing to signal it", 2
+        )
+    cmdline = _proc_cmdline(pid)
+    if cmdline is not None and not _looks_like_duet_cmdline(cmdline):
+        raise StopTargetError(
+            f"PID {pid} belongs to a foreign process; refusing to signal it", 2
+        )
+    return run_dir, pid
+
+
+def request_run_stop(arg: str, *, immediate: bool = False) -> int:
+    """Signal one validated supervisor. Return 0=sent, 2=unsafe, 3=error."""
+    try:
+        run_dir, pid = _validated_stop_target(arg)
+        # Re-read all identity evidence immediately before the signal. This
+        # narrows the unavoidable check/signal race and catches state changes.
+        checked_dir, checked_pid = _validated_stop_target(str(run_dir))
+        if checked_dir != run_dir or checked_pid != pid:
+            raise StopTargetError("run supervisor identity changed during stop", 2)
+        if not immediate and STOP_GRACEFUL_SIGNAL is None:
+            raise StopTargetError(
+                "this platform has no run-scoped graceful stop signal", 2
+            )
+        stop_signal = (
+            STOP_IMMEDIATE_SIGNAL if immediate else STOP_GRACEFUL_SIGNAL
+        )
+        os.kill(pid, stop_signal)
+    except StopTargetError as exc:
+        print(f"[duet] stop refused: {exc}", file=sys.stderr)
+        return exc.exit_code
+    except ProcessLookupError:
+        print(
+            f"[duet] stop refused: duet supervisor PID {pid} became stale",
+            file=sys.stderr,
+        )
+        return 2
+    except PermissionError:
+        print(
+            f"[duet] stop refused: permission denied for duet supervisor PID {pid}",
+            file=sys.stderr,
+        )
+        return 2
+
+    mode = "immediate" if immediate else "graceful"
+    print(f"[duet] {mode} stop requested for {run_dir} (supervisor PID {pid})")
+    return 0
+
+
 def _load_run_state(run_dir: pathlib.Path,
                     parser: argparse.ArgumentParser,
                     option_name: str) -> dict:
@@ -4627,6 +4953,26 @@ def print_runs_list(explicit_path: Optional[pathlib.Path]) -> int:
     return 0
 
 
+def _add_control_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--continue", metavar="RUN_DIR_OR_ID", dest="continue_run",
+        help="start a new run from an existing run's state.json: restore "
+             "agents/session ids, reuse its worktree when available, and send "
+             "the next agent a continuation kickoff. Seed flags can add guidance.",
+    )
+    parser.add_argument(
+        "--stop", metavar="RUN_DIR_OR_ID", default=None,
+        help="request a graceful stop for one live run. Resolves like --status, "
+             "proves the exact supervisor PID and process-start identity, then "
+             "signals only that PID. The current child turn can finish.",
+    )
+    parser.add_argument(
+        "--immediate", action="store_true",
+        help="with --stop, terminate that run's active child process group and "
+             "finish the run with reason=force_stop",
+    )
+
+
 def _build_arg_parser() -> argparse.ArgumentParser:
     ap = argparse.ArgumentParser(
         description="duet — two CLI agents in conversation, with per-agent session memory.")
@@ -4639,11 +4985,7 @@ def _build_arg_parser() -> argparse.ArgumentParser:
                          "its latest message and feed it to the partner agent.")
     ap.add_argument("--resume-codex", metavar="SESSION_ID",
                     help="(advanced) seed codex with an existing session id.")
-    ap.add_argument("--continue", metavar="RUN_DIR_OR_ID", dest="continue_run",
-                    help="start a new run from an existing run's state.json: "
-                         "restore agents/session ids, reuse its worktree when "
-                         "available, and send the next agent a continuation kickoff. "
-                         "--task/--kickoff/--task-from-cmd may add optional guidance.")
+    _add_control_arguments(ap)
     ap.add_argument("--task", help="task description, @file, or @- stdin "
                                    "(used if no --resume-* and no --kickoff)")
     ap.add_argument("--kickoff", help="explicit first message, @file, or @- stdin "
@@ -4730,8 +5072,8 @@ def _build_arg_parser() -> argparse.ArgumentParser:
                          "`add_dirs:` (list).")
     ap.add_argument("--reasoning", choices=REASONING_LEVELS, default=None,
                     help="reasoning effort for both agents. Codex: passes "
-                         "`-c model_reasoning_effort=<v>` except for medium "
-                         "(max → xhigh). Claude: passes `--effort <v>` "
+                         "`-c model_reasoning_effort=<v>` unchanged. Claude: "
+                         "passes `--effort <v>` "
                          "(minimal → low) and adds high/xhigh/max prompt nudges. "
                          "Copilot: passes `--effort <v>` (minimal → none). "
                          "Gemini: no effort flag; high/xhigh/max are prompt nudges only.")
@@ -5154,6 +5496,15 @@ def main() -> int:
     ap = _build_arg_parser()
     args = ap.parse_args()
 
+    if args.immediate and args.stop is None:
+        ap.error("--immediate is only valid with --stop")
+    if args.stop is not None:
+        if args.status or args.list_runs is not None or args.continue_run:
+            ap.error("--stop cannot be combined with --status, --list, or --continue")
+        if args.json_output:
+            ap.error("--json is only valid with --status")
+        return request_run_stop(args.stop, immediate=args.immediate)
+
     # `--status` is read-only: print run health and exit. Skip everything below.
     if args.status:
         return print_run_status_safe(args.status, json_output=args.json_output)

{duet_cli-0.2.10 → duet_cli-0.2.12/duet_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: duet-cli
-Version: 0.2.10
+Version: 0.2.12
 Summary: Two CLI agents in conversation. One Python file. Stdlib only.
 Author: Volkan Altan
 License-Expression: MIT
@@ -235,9 +235,19 @@ stop, duet opens a `force>` prompt so you can push another round.
 Every run writes a directory with `transcript.md`, `state.json`, per-turn
 stderr logs, and the `wt/` worktree when `--worktree` is on. Inspect a run with
 `duet --status <run-id> --json` (or omit `--json` for the human view), list runs
-with `duet --list`, and start a fresh run
+with `duet --list`, stop one exact live run with `duet --stop <run-id>`, and
+start a fresh run
 from saved state with `duet --continue <run> --task "next thing"`.
 
+`--stop` is graceful. It lets the current agent turn finish before duet records
+`force_stop`. Use `--stop <run-id> --immediate` to terminate that run's active
+child and record `force_stop` now. Both forms validate the saved supervisor PID
+and process-start identity. They never use a process-name match or signal a
+different duet run.
+
+If status remains `awaiting_force`, press Enter in the original terminal.
+Some platforms do not wake the blocking `force>` input after an external signal.
+
 - **Backends:** `claude`, `codex`, `gemini`, `copilot`, `opencode`
 - **Roles:** `planner`, `coder`, `reviewer`, `triage-reviewer`, or a custom one
 - **Reasoning:** `--reasoning minimal|low|medium|high|xhigh|max`
@@ -254,7 +264,7 @@ a deep-reasoning turn is stuck.
 
 [docs/USAGE.md](https://github.com/volkan/duet/blob/main/docs/USAGE.md) is the
 full reference: every flag, reasoning levels, session memory, output layout,
-`--status` / `--continue`, the force prompt, Codex sandbox and network rules,
+`--status` / `--stop` / `--continue`, the force prompt, Codex sandbox and network rules,
 and worktree mode.
 
 ## Contributing

{duet_cli-0.2.10 → duet_cli-0.2.12}/duet_cli.egg-info/SOURCES.txt

@@ -10,4 +10,5 @@ duet_cli.egg-info/requires.txt
 duet_cli.egg-info/top_level.txt
 tests/test_bump_release_version.py
 tests/test_control_plane.py
-tests/test_duet.py
+tests/test_duet.py
+tests/test_stop_control_plane.py

{duet_cli-0.2.10 → duet_cli-0.2.12}/tests/test_control_plane.py

@@ -224,6 +224,39 @@ class TestRunInfoAndLaunchFailures(unittest.TestCase):
                     contextlib.redirect_stderr(io.StringIO()):
                 duet._setup_run_worktree(cfg, "run", root)
 
+    def test_immediate_stop_during_worktree_setup_is_force_stop(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            root = pathlib.Path(raw).resolve()
+            info = root / "run.json"
+            cfg = self._cfg(root, info, task="x", worktree=True)
+            installed: dict[str, duet.StopFlag] = {}
+
+            def capture_stop(stop: duet.StopFlag) -> None:
+                installed["stop"] = stop
+
+            def interrupted_setup(*_args):
+                installed["stop"].request("SIGTERM")
+                raise duet.RunSetupError("interrupted setup")
+
+            with mock.patch.object(duet, "_install_sigint"), \
+                    mock.patch.object(
+                        duet, "_install_sigterm", side_effect=capture_stop
+                    ), \
+                    mock.patch.object(
+                        duet, "_setup_run_worktree", side_effect=interrupted_setup
+                    ), \
+                    mock.patch.object(duet, "_register_run_in_home_index"), \
+                    contextlib.redirect_stdout(io.StringIO()), \
+                    contextlib.redirect_stderr(io.StringIO()):
+                state = duet.run_duet(cfg)
+
+            self.assertEqual(state["phase"], "finished")
+            self.assertEqual(state["finished_reason"], "force_stop")
+            saved = json.loads(
+                pathlib.Path(json.loads(info.read_text())["state_path"]).read_text()
+            )
+            self.assertEqual(saved["finished_reason"], "force_stop")
+
     def test_kickoff_failure_is_terminal_but_status_stays_secret_minimized(self) -> None:
         with tempfile.TemporaryDirectory() as raw:
             root = pathlib.Path(raw).resolve()
@@ -459,6 +492,169 @@ class TestStatusSchema(unittest.TestCase):
             self.assertIn("JSONDecodeError", snapshot["error"])
 
 
+class TestRunScopedStopValidation(unittest.TestCase):
+    def _run(self, root: pathlib.Path, **overrides) -> pathlib.Path:
+        run = root / "20260719-120000"
+        run.mkdir()
+        state = {
+            "phase": "turn_running",
+            "finished_reason": None,
+            "duet_pid": 123,
+            "duet_process_start": "start-123",
+        }
+        state.update(overrides)
+        (run / "state.json").write_text(json.dumps(state), encoding="utf-8")
+        return run
+
+    def test_invalid_pid_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw), duet_pid="invalid")
+            with mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_ambiguous_bare_run_id_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            root = pathlib.Path(raw)
+            run_id = "20260719-120000"
+            roots = [root / "one", root / "two"]
+            for candidate_root in roots:
+                (candidate_root / run_id).mkdir(parents=True)
+            with mock.patch.object(
+                    duet, "_default_list_paths", return_value=roots), \
+                    mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()) as stderr:
+                self.assertEqual(duet.request_run_stop(run_id), 2)
+            self.assertIn("ambiguous", stderr.getvalue())
+            self.assertIn("explicit run directory path", stderr.getvalue())
+            kill.assert_not_called()
+
+    def test_stale_pid_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw))
+            with mock.patch.object(duet, "_pid_alive", return_value=False), \
+                    mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_terminal_run_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(
+                pathlib.Path(raw), phase="finished", finished_reason="max_turns"
+            )
+            with mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_pid_one_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw), duet_pid=1)
+            with mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_reused_pid_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw))
+            with mock.patch.object(duet, "_pid_alive", return_value=True), \
+                    mock.patch.object(
+                        duet, "_proc_start_identity", return_value="new-start"
+                    ), \
+                    mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_foreign_process_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw))
+            with mock.patch.object(duet, "_pid_alive", return_value=True), \
+                    mock.patch.object(
+                        duet, "_proc_start_identity", return_value="start-123"
+                    ), \
+                    mock.patch.object(
+                        duet, "_proc_cmdline", return_value="python worker.py"
+                    ), \
+                    mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_missing_start_identity_is_refused_without_signal(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            run = self._run(pathlib.Path(raw), duet_process_start=None)
+            with mock.patch.object(duet, "_pid_alive", return_value=True), \
+                    mock.patch.object(duet.os, "kill") as kill, \
+                    contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(duet.request_run_stop(str(run)), 2)
+            kill.assert_not_called()
+
+    def test_graceful_and_immediate_signal_only_exact_supervisor_pid(self) -> None:
+        for immediate, expected_signal in (
+                (False, duet.STOP_GRACEFUL_SIGNAL),
+                (True, duet.signal.SIGTERM)):
+            with self.subTest(immediate=immediate), \
+                    tempfile.TemporaryDirectory() as raw:
+                run = self._run(pathlib.Path(raw))
+                with mock.patch.object(duet, "_pid_alive", return_value=True), \
+                        mock.patch.object(
+                            duet, "_proc_start_identity", return_value="start-123"
+                        ), \
+                        mock.patch.object(duet, "_proc_cmdline", return_value=None), \
+                        mock.patch.object(duet.os, "kill") as kill, \
+                        contextlib.redirect_stdout(io.StringIO()):
+                    self.assertEqual(
+                        duet.request_run_stop(str(run), immediate=immediate), 0
+                    )
+                kill.assert_called_once_with(123, expected_signal)
+
+    def test_repeated_run_stop_signal_does_not_hard_exit(self) -> None:
+        if duet.STOP_GRACEFUL_SIGNAL is None:
+            self.skipTest("platform has no run-scoped graceful stop signal")
+        stop = duet.StopFlag()
+        with mock.patch.object(duet.signal, "signal") as install, \
+                mock.patch.object(duet.os, "_exit") as hard_exit, \
+                contextlib.redirect_stderr(io.StringIO()):
+            duet._install_run_stop_signal(stop)
+            handler = install.call_args.args[1]
+            handler(duet.STOP_GRACEFUL_SIGNAL, None)
+            handler(duet.STOP_GRACEFUL_SIGNAL, None)
+        self.assertTrue(stop.requested)
+        self.assertEqual(stop.reason, "run_stop")
+        hard_exit.assert_not_called()
+
+    def test_force_prompt_records_stop_after_tty_input_unblocks(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            root = pathlib.Path(raw)
+            cfg = duet.DuetConfig(cwd=root, agents=_agents(), task="x")
+            stop = duet.StopFlag()
+
+            def unblock_prompt(_prompt: str) -> str:
+                stop.request("SIGTERM")
+                return ""
+
+            with mock.patch.object(duet.sys.stdin, "isatty", return_value=True), \
+                    mock.patch("builtins.input", side_effect=unblock_prompt), \
+                    contextlib.redirect_stdout(io.StringIO()):
+                reason, _ = duet.ask_force(
+                    cfg,
+                    [],
+                    root / "transcript.md",
+                    root / "state.json",
+                    "last message",
+                    1,
+                    {agent.name: False for agent in cfg.agents},
+                    "max_turns",
+                    stop=stop,
+                )
+
+            self.assertEqual(reason, "force_stop")
+
+
 class TestContinueWorktreeOverrides(unittest.TestCase):
     def _write_prior_run(
         self,
@@ -619,7 +815,7 @@ class TestTimeoutContinueLoop(unittest.TestCase):
 
         def skip_force(_cfg, _history, _transcript_path, _state_path,
                        _last_msg, _speaker_idx, _seen_first_turn, reason,
-                       _wt_path=None, _wt_branch=None):
+                       _wt_path=None, _wt_branch=None, **_kwargs):
             return reason, None
 
         err = io.StringIO()

{duet_cli-0.2.10 → duet_cli-0.2.12}/tests/test_duet.py

@@ -1045,10 +1045,13 @@ class TestReasoningHelpers(unittest.TestCase):
                 self.assertIn(level, duet.COPILOT_REASONING_PROMPT_PREFIX)
                 self.assertIn(level, duet.OPENCODE_REASONING_PROMPT_PREFIX)
 
-    def test_codex_max_maps_to_xhigh(self) -> None:
-        # Codex documents `xhigh` but not `max`; duet keeps `max` as a
-        # backend-normalized alias for the highest Codex effort.
-        self.assertEqual(duet.CODEX_REASONING_MAP["max"], "xhigh")
+    def test_codex_reasoning_levels_pass_through_exactly(self) -> None:
+        # Model support varies. Duet must not silently change the requested
+        # value before Codex validates it for the selected model.
+        self.assertEqual(
+            duet.CODEX_REASONING_MAP,
+            {level: level for level in duet.REASONING_LEVELS},
+        )
 
 
 class TestAgentExitError(unittest.TestCase):

duet_cli-0.2.12/tests/test_stop_control_plane.py

@@ -0,0 +1,200 @@
+"""Process-level regression tests for run-scoped shutdown."""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+
+import duet
+
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+DUET = ROOT / "duet.py"
+
+
+def _wait_for(predicate, message: str, timeout: float = 8.0):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        value = predicate()
+        if value:
+            return value
+        time.sleep(0.02)
+    raise AssertionError(message)
+
+
+def _read_json_if_ready(path: pathlib.Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _active_child_pid(run_dir: pathlib.Path):
+    for pid_file in run_dir.glob("turn-*.pid"):
+        try:
+            pid = int(pid_file.read_text(encoding="utf-8").strip())
+        except (OSError, ValueError):
+            continue
+        if duet._pid_alive(pid):
+            return pid
+    return None
+
+
+@unittest.skipIf(sys.platform == "win32", "requires POSIX signals")
+class TestRunScopedStop(unittest.TestCase):
+    def test_immediate_stop_isolated_to_selected_live_run(self) -> None:
+        with tempfile.TemporaryDirectory() as raw:
+            root = pathlib.Path(raw).resolve()
+            bin_dir = root / "bin"
+            bin_dir.mkdir()
+            fake_backend = bin_dir / "claude"
+            fake_backend.write_text(
+                "#!/usr/bin/env python3\n"
+                "import time\n"
+                "while True:\n"
+                "    time.sleep(1)\n",
+                encoding="utf-8",
+            )
+            fake_backend.chmod(0o755)
+            env = os.environ.copy()
+            env["PATH"] = str(bin_dir) + os.pathsep + env.get("PATH", "")
+
+            supervisors: list[subprocess.Popen] = []
+            run_dirs: list[pathlib.Path] = []
+            child_pids: list[int] = []
+            supervisor_starts: list[str] = []
+            child_starts: list[str] = []
+            try:
+                for label in ("a", "b"):
+                    work = root / label
+                    work.mkdir()
+                    info = root / f"{label}.json"
+                    proc = subprocess.Popen(
+                        [
+                            sys.executable, str(DUET),
+                            "--cwd", str(work),
+                            "--runs-dir", str(work / "runs"),
+                            "--run-info-file", str(info),
+                            "--lead", "claude:planner",
+                            "--partner", "claude:coder",
+                            "--task", "wait for shutdown",
+                            "--turns", "2",
+                            "--timeout", "60",
+                            "--no-worktree",
+                            "--quiet",
+                        ],
+                        stdin=subprocess.DEVNULL,
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        env=env,
+                        start_new_session=True,
+                    )
+                    supervisors.append(proc)
+                    supervisor_starts.append(_wait_for(
+                        lambda p=proc.pid: duet._proc_start_identity(p),
+                        f"cannot identify supervisor for run {label}",
+                    ))
+                    launch = _wait_for(
+                        lambda p=info: _read_json_if_ready(p),
+                        f"run {label} did not publish run info",
+                    )
+                    run_dir = pathlib.Path(launch["run_dir"])
+                    run_dirs.append(run_dir)
+                    child_pid = _wait_for(
+                        lambda p=run_dir: _active_child_pid(p),
+                        f"run {label} did not start its backend child",
+                    )
+                    child_pids.append(child_pid)
+                    child_starts.append(_wait_for(
+                        lambda p=child_pid: duet._proc_start_identity(p),
+                        f"cannot identify backend child for run {label}",
+                    ))
+
+                for _ in range(2):
+                    graceful = subprocess.run(
+                        [
+                            sys.executable, str(DUET),
+                            "--stop", str(run_dirs[0]),
+                        ],
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        env=env,
+                        timeout=10,
+                    )
+                    self.assertEqual(
+                        graceful.returncode, 0,
+                        graceful.stdout + graceful.stderr,
+                    )
+                    time.sleep(0.1)
+                self.assertIsNone(
+                    supervisors[0].poll(),
+                    "repeated graceful stop hard-exited the supervisor",
+                )
+
+                stopped = subprocess.run(
+                    [
+                        sys.executable, str(DUET),
+                        "--stop", str(run_dirs[0]),
+                        "--immediate",
+                    ],
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    env=env,
+                    timeout=10,
+                )
+                self.assertEqual(
+                    stopped.returncode, 0, stopped.stdout + stopped.stderr
+                )
+                _wait_for(
+                    lambda: supervisors[0].poll() is not None,
+                    "selected supervisor did not exit",
+                )
+                state_a = _wait_for(
+                    lambda: _read_json_if_ready(run_dirs[0] / "state.json"),
+                    "selected run did not retain readable state",
+                )
+                self.assertEqual(state_a["phase"], "finished")
+                self.assertEqual(state_a["finished_reason"], "force_stop")
+                self.assertFalse(duet._pid_alive(child_pids[0]))
+
+                self.assertIsNone(supervisors[1].poll())
+                self.assertTrue(duet._pid_alive(supervisors[1].pid))
+                self.assertTrue(duet._pid_alive(child_pids[1]))
+            finally:
+                # Cleanup is exact and fail-closed. Never match process names.
+                for pid, started in zip(child_pids, child_starts):
+                    self._kill_validated(pid, str(fake_backend), started)
+                for proc, run_dir, started in zip(
+                        supervisors, run_dirs, supervisor_starts):
+                    self._kill_validated(proc.pid, str(run_dir.parent), started)
+                    try:
+                        proc.wait(timeout=3)
+                    except subprocess.TimeoutExpired:
+                        self._kill_validated(
+                            proc.pid, str(run_dir.parent), started, signal.SIGKILL
+                        )
+                        proc.wait(timeout=3)
+
+    def _kill_validated(self, pid: int, expected: str, saved_start: str,
+                        sig: int = signal.SIGTERM) -> None:
+        if not duet._pid_alive(pid):
+            return
+        self.assertEqual(duet._proc_start_identity(pid), saved_start)
+        command = duet._proc_cmdline(pid)
+        if command is not None:
+            self.assertIn(expected, command)
+        os.kill(pid, sig)
+
+
+if __name__ == "__main__":
+    unittest.main()