add Strix Checkpoint Feature (Custom Modification) resume/checkpoint system for interrupted scans

[Ahmex000]

Strix Checkpoint Feature (Custom Modification)

I implemented a simple modification that introduces an important feature:
the ability to stop a running scan and resume it later without losing progress or restarting from scratch.

🔹 How It Works

Run Strix with a --run-name to create a checkpoint:

strix --target http://php.testinvicti.com/ --run-name my-scan

• This saves a checkpoint under the name: my-scan.
• You can resume the scan at any time using the same command.

🔹 Starting a New Scan with the Same Name

If you want to start a fresh scan using the same name:

strix --target http://php.testinvicti.com/ --run-name my-scan --new

🔹 Using a Different Checkpoint Name

Alternatively, you can simply use a new run name:

strix --target http://php.testinvicti.com/ --run-name my-scan-2

• Note : I have fixed the issue that was in the previous code https://github.com/usestrix/strix/pull/373 , where you could only create one checkpoint, but in the latest update you can complete more than once.

• Note : I have fixed the issue that was in the previous code https://github.com/usestrix/strix/pull/378 Previously, there were some issues with file locations, but the process is now easier and lighter on the system.

The current version works without any problems, and you can pause and resume scans multiple times.

[greptile-apps]

Greptile Summary

This PR introduces a checkpoint/resume system for interrupted Strix scans, allowing users to pause a running pentest and continue it later via --run-name, --resume, and --new CLI flags. The overall architecture is well thought-out — atomic checkpoint writes, thread-safe agent registry locking, Docker container race condition fixes, and clean integration into both CLI and TUI paths. However there are four issues that need to be resolved before merging:

• Checkpoint re-saved after clean completion (CLI + TUI): The atexit-registered cleanup_on_exit in cli.py and the equivalent closure in tui.py's _setup_cleanup_handlers both call _save_checkpoint_on_interrupt() / _save_checkpoint_on_interrupt() unconditionally on process exit. When a scan completes successfully, base_agent.py correctly deletes the checkpoint — but then the exit handler fires and writes it back. The same issue exists in tui.py's action_custom_quit. Every successful scan will leave a stale checkpoint, causing the next run to incorrectly auto-resume a finished scan.
• Infinite recursion in _depth() (checkpoint_restore.py): The memoisation guard is written after the recursive call, so a cyclic parent_id reference (possible with a corrupted checkpoint file) causes unbounded recursion and a RecursionError. Setting _memo[aid] = 0 before recursing into the parent breaks the cycle.
• LLM API key precedence reversed (config.py): An unrelated change makes stored LLM credentials in cli-config.json unconditionally override shell environment variables, reversing the previous behaviour where the shell always won. Users who rotate API keys via shell env (a common pattern) will silently have the old stored key applied.

Confidence Score: 2/5

• Not safe to merge — three P1 bugs need to be fixed before the feature can be relied upon.
• The checkpoint architecture and Docker/threading fixes are solid, but two independent logic bugs (post-completion checkpoint re-save in both CLI and TUI, and the cyclic recursion in _depth) would cause incorrect behaviour on every normal scan run. The config.py precedence reversal is an unrelated breaking change for any user who manages LLM credentials via shell env vars.
• strix/interface/cli.py, strix/interface/tui.py (checkpoint saved after clean completion in both atexit and quit handlers), strix/interface/checkpoint_restore.py (_depth infinite recursion), strix/config/config.py (LLM env var precedence reversal)

Important Files Changed

Filename	Overview
strix/telemetry/checkpoint.py	New file implementing CheckpointModel (Pydantic), CheckpointManager (atomic save/load/delete), and compute_target_hash. Design is solid: atomic writes via .tmp → rename, non-fatal errors, version field. No issues found here.
strix/interface/checkpoint_restore.py	New shared helpers for restoring state on resume. Contains a critical infinite recursion bug in _depth() when checkpoint data has cyclic parent_id references — the memo is written after recursing, so cycles are not detected. Also writes to _agent_graph outside the _agents_lock, inconsistent with other guarded writes in this module.
strix/interface/cli.py	Checkpoint/resume wiring for the CLI runner. Critical bug: cleanup_on_exit (atexit) calls _save_checkpoint_on_interrupt() unconditionally, re-creating the checkpoint after a successful scan that already deleted it. The next run will incorrectly auto-resume a completed scan.
strix/interface/tui.py	Checkpoint/resume wiring for the TUI. Same post-completion checkpoint re-save bug as cli.py appears in both action_custom_quit and the atexit cleanup closure in _setup_cleanup_handlers.
strix/config/config.py	Unrelated behavior change: LLM env vars in cli-config.json now always override shell environment variables, reversing the previous precedence. Breaks users who manage API keys via shell env — their shell key is silently ignored in favour of potentially stale stored credentials.
strix/interface/main.py	Adds --run-name, --resume, and --new CLI flags plus _setup_checkpoint_on_args() and _find_checkpoint_by_target_hash(). Logic is well-structured with proper fallbacks (auto-generate name, target-hash mismatch warning, corruption warning). Results path changed to ~/strix_runs consistently.
strix/agents/base_agent.py	Clean integration: checkpoint saved after every iteration (root agents only), deleted on clean completion, task message skipped when resuming. Non-intrusive — zero impact when checkpoint_manager is absent.
strix/runtime/docker_runtime.py	Adds _container_init_lock to prevent multiple resumed sub-agent threads from racing to create the same Docker container. _cleanup_existing_containers uses synchronous subprocess.run for docker rm -f to avoid Docker name-registry race. Well-reasoned changes.
strix/tools/agents_graph/agents_graph_actions.py	Adds _agents_lock used consistently around _running_agents and _agent_instances mutations. Filters resume marker messages from inherited context so sub-agents don't misinterpret the root's resume instructions. Improved error message for missing agent IDs.

Comments Outside Diff (1)

1. strix/interface/tui.py, line 854-873 (link)

   TUI cleanup handler also saves after clean completion

   The _save_checkpoint_on_interrupt() closure defined inside _setup_cleanup_handlers is also called from cleanup_on_exit (atexit). This duplicates the same race described in action_custom_quit: a successful scan deletes the checkpoint in base_agent.py, then atexit fires and re-saves it. Apply the same completed guard here so the cleanup path is consistent with the recommended fix above.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: strix/interface/tui.py
   Line: 854-873
   
   Comment:
   **TUI cleanup handler also saves after clean completion**
   
   The `_save_checkpoint_on_interrupt()` closure defined inside `_setup_cleanup_handlers` is also called from `cleanup_on_exit` (atexit). This duplicates the same race described in `action_custom_quit`: a successful scan deletes the checkpoint in `base_agent.py`, then atexit fires and re-saves it. Apply the same `completed` guard here so the cleanup path is consistent with the recommended fix above.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: strix/interface/cli.py
Line: 263-285

Comment:
**Checkpoint saved after clean scan completion**

`_save_checkpoint_on_interrupt` is called unconditionally from `cleanup_on_exit`, which is registered with `atexit`. When a scan completes successfully, `base_agent.py` calls `checkpoint_manager.delete()`, but then as the process exits normally, `atexit` triggers `cleanup_on_exit()` → `_save_checkpoint_on_interrupt()`. At that point `_checkpoint_saved` is **not** set (no interrupt occurred), so the guard passes and the checkpoint is **written back** over the deletion.

The consequence is that after every successful scan, a stale checkpoint file is left on disk. The next time the user runs the same `--run-name`, Strix will detect the checkpoint and auto-resume a scan that already finished, replaying all previous findings and re-running the agent from a "completed" state.

Add a guard that skips the save when the agent finished cleanly:

```python
def _save_checkpoint_on_interrupt() -> None:
    """Persist current agent state before exit so the scan can be resumed."""
    if not checkpoint_manager or not _agent_ref:
        return
    if _checkpoint_saved.is_set():
        return
    agent_instance = _agent_ref[0]
    # Skip if the scan already completed successfully — the checkpoint
    # was deleted in base_agent.py and there is nothing to resume.
    if getattr(agent_instance.state, "completed", False):
        return
    _checkpoint_saved.set()
    try:
        checkpoint_manager.save(
            agent_instance.state,
            tracer,
            scan_config,
            target_hash,
            agent_instance.max_iterations,
        )
    except Exception:  # noqa: BLE001
        pass  # non-fatal
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: strix/interface/tui.py
Line: 2020-2031

Comment:
**TUI also saves checkpoint after clean scan completion**

`action_custom_quit` unconditionally calls `_mgr.save(...)` before exiting. If the scan ran to completion, `base_agent.py` already deleted the checkpoint via `checkpoint_manager.delete()`. This code then immediately re-creates it, so the next run finds a stale checkpoint for a completed scan and auto-resumes it.

The same `completed` flag guard recommended for `cli.py` should be applied here:

```python
if _mgr and _agent:
    import contextlib
    # Only save if the scan was interrupted, not if it finished cleanly.
    if not getattr(_agent.state, "completed", False):
        with contextlib.suppress(Exception):
            _mgr.save(
                _agent.state,
                self.tracer,
                self.scan_config,
                self.agent_config.get("target_hash", ""),
                _agent.max_iterations,
            )
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: strix/interface/checkpoint_restore.py
Line: 34-43

Comment:
**Infinite recursion on cyclic `parent_id` references**

`_depth()` uses memoisation to avoid re-computation, but the memo entry for `aid` is only written **after** `_depth(parent)` returns. If the checkpoint data contains a cycle (e.g., agent A's `parent_id` is B and B's is A — possible with a corrupted checkpoint), the call stack grows unboundedly:

```
_depth("A") → _depth("B") → _depth("A") → _depth("B") → ... RecursionError
```

Fix: mark `aid` as visited (depth 0) **before** recursing, so any back-edge resolves immediately:

```python
def _depth(aid: str) -> int:
    if aid in _memo:
        return _memo[aid]
    # Mark before recursing to break any cycle
    _memo[aid] = 0
    parent = sub_agent_states.get(aid, {}).get("parent_id")
    if parent is not None and parent in sub_agent_states:
        _memo[aid] = 1 + _depth(parent)
    return _memo[aid]
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: strix/config/config.py
Line: 144-150

Comment:
**LLM API key precedence silently reversed**

The original code treated shell environment variables as the authoritative source for LLM credentials:

```python
# old logic (simplified)
if var_name not in os.environ or force:
    os.environ[var_name] = var_value
```

The new code makes `cli-config.json` **always win** over the shell for LLM vars:

```python
if var_name in llm_vars or force or var_name not in os.environ:
    os.environ[var_name] = var_value
```

This means if a user has `ANTHROPIC_API_KEY` set in their shell (e.g., pointing to a new or rotated key) and an older key is stored in `~/.strix/cli-config.json`, the **stored** key now silently overrides the shell key. The user's scan will fail authentication with no clear indication of why.

This looks unrelated to the checkpoint feature and is a breaking change for anyone who manages LLM credentials via shell environment variables. Consider reverting this specific hunk or adding a warning when the stored key overrides the shell value.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: strix/interface/tui.py
Line: 854-873

Comment:
**TUI cleanup handler also saves after clean completion**

The `_save_checkpoint_on_interrupt()` closure defined inside `_setup_cleanup_handlers` is also called from `cleanup_on_exit` (atexit). This duplicates the same race described in `action_custom_quit`: a successful scan deletes the checkpoint in `base_agent.py`, then atexit fires and re-saves it. Apply the same `completed` guard here so the cleanup path is consistent with the recommended fix above.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "Fix all critical iss..."}

[Ahmex000]

2026-03-21.11-02-02.mp4