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 Strix scans, allowing users to pause and continue interrupted penetration tests without losing progress. The feature is activated via --run-name, --resume, and --new CLI flags, and checkpoints are saved atomically after each agent iteration to ~/strix_runs/<run-name>/checkpoint.json.

Key changes:

• strix/telemetry/checkpoint.py (new): CheckpointManager with atomic write (.tmp → rename), CheckpointModel Pydantic schema, and compute_target_hash for checkpoint validation.
• strix/interface/checkpoint_restore.py (new): restore_sub_agents spawns previously-running sub-agents from checkpoint state in topological order; build_root_resume_message injects a resume context message into the root agent.
• strix/agents/base_agent.py: Saves checkpoint after every successful iteration (root agents only) and deletes it on clean completion; is_resumed flag suppresses the duplicate task message.
• strix/interface/cli.py / tui.py: Resume banner, previous-findings replay, checkpoint manager wiring, and a completed guard that prevents re-saving the checkpoint after a clean scan finish (addressing prior review concerns).
• strix/runtime/docker_runtime.py: Adds _container_init_lock and synchronous _cleanup_existing_containers (via subprocess.run docker rm) to prevent multi-thread container creation races on resume.
• strix/tools/agents_graph/agents_graph_actions.py: Adds _agents_lock for thread-safe access to _running_agents / _agent_instances; strips resume system messages from inherited sub-agent context.

Two concerns remain in checkpoint_restore.py:

1. The _run closure that drives restored sub-agents does not replicate the graph-cleanup logic from _run_agent_in_thread — restored sub-agents permanently show status: \"running\" in view_agent_graph after they finish, which may confuse the root agent.
2. t.start() is called before the agent is registered in _agent_instances and _agent_graph[\"nodes\"], reversing the ordering used in create_agent and creating a small race window.

Confidence Score: 4/5

Safe to merge for most use cases; two P2 issues in restore_sub_agents may cause stale graph state for multi-agent resumed scans.

The core checkpoint save/load/delete cycle, atomic writes, interrupt guards, and the completed-flag fixes are all correct. The two open issues (stale graph status for restored sub-agents and reversed thread-start vs registration order) only affect the multi-sub-agent resume path and don't cause data loss or crashes — they could cause the root agent LLM to see a slightly inconsistent graph view, potentially leading to duplicated sub-agent spawning in edge cases.

strix/interface/checkpoint_restore.py — the _run closure needs graph-cleanup logic and thread registration should happen before t.start()

Important Files Changed

Filename	Overview
strix/telemetry/checkpoint.py	New file: CheckpointModel (Pydantic), CheckpointManager with atomic write (.tmp → rename), load, delete, and compute_target_hash helper. Logic is sound and non-fatal on I/O errors.
strix/interface/checkpoint_restore.py	New file: restore_sub_agents starts sub-agents in daemon threads without proper graph-status cleanup on exit, and registers agents after thread start (reversed order vs. create_agent). build_root_resume_message is well structured.
strix/interface/cli.py	Adds resume banner, output replay, checkpoint manager wiring, and interrupt handlers with completed-guard. Previous-thread concerns about stale checkpoint on clean completion are now fixed.
strix/interface/tui.py	Mirrors cli.py resume support: restores tracer state, wires checkpoint manager, adds completed-guard before saving on quit. Previous-thread stale-checkpoint issue is addressed.
strix/interface/main.py	Adds --run-name, --resume, --new CLI flags and _setup_checkpoint_on_args which handles all four cases: force-new, auto-detect by target hash, explicit run name with checkpoint, explicit run name without. Target-hash mismatch warning is clear.
strix/agents/base_agent.py	Adds checkpoint_manager save call after each successful iteration (root agents only) and delete on clean completion. is_resumed flag prevents duplicate task message injection.
strix/runtime/docker_runtime.py	Adds _container_init_lock to prevent multiple threads from racing to create a container on resume, and _cleanup_existing_containers using synchronous docker CLI rm to avoid the async SDK race where the name registry still holds the name.
strix/tools/agents_graph/agents_graph_actions.py	Adds _agents_lock threading.Lock to protect _running_agents and _agent_instances; strips resume system messages from inherited context to prevent sub-agent confusion.
strix/config/config.py	Removes _llm_env_changed guard (stale LLM keys no longer auto-purged from stored config) and refactors apply logic. The effective precedence rule (shell env wins when set) is unchanged, but see prior thread discussion.

Prompt To Fix All With AI

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

Comment:
**Restored sub-agents never update graph status on completion**

The `_run` closure calls `agent.agent_loop()` but does nothing when the loop exits. In the normal path (`_run_agent_in_thread`), the thread wrapper updates the agent graph node status to `"completed"` or `"error"` and pops the agent from `_running_agents` / `_agent_instances`:

```python
# _run_agent_in_thread (agents_graph_actions.py) — NOT done by _run
_agent_graph["nodes"][state.agent_id]["status"] = "completed"
_agent_graph["nodes"][state.agent_id]["finished_at"] = datetime.now(UTC).isoformat()
with _agents_lock:
    _running_agents.pop(state.agent_id, None)
    _agent_instances.pop(state.agent_id, None)
```

Because `_run` omits this, every restored sub-agent permanently shows `status: "running"` in `view_agent_graph` after it finishes. The root agent may conclude those sub-agents are still alive, avoid re-spawning needed work, or wait indefinitely for results that have already been delivered.

Consider replacing the bare `_run` closure with a call to `_run_agent_in_thread`, or at minimum replicating the graph-cleanup logic inside `_run`'s `finally` block:

```python
def _run(a: Any = agent, s: Any = state) -> None:
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        loop.run_until_complete(a.agent_loop(s.task))
    except Exception:  # noqa: BLE001
        with contextlib.suppress(Exception):
            agents_graph_actions._agent_graph["nodes"][s.agent_id]["status"] = "error"
    else:
        with contextlib.suppress(Exception):
            agents_graph_actions._agent_graph["nodes"][s.agent_id]["status"] = "completed"
    finally:
        loop.close()
        with contextlib.suppress(Exception):
            with agents_graph_actions._agents_lock:
                agents_graph_actions._running_agents.pop(s.agent_id, None)
                agents_graph_actions._agent_instances.pop(s.agent_id, None)
```

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: 83-100

Comment:
**Thread starts before agent is registered in the global registry**

`t.start()` is called before the agent is inserted into `_agent_instances`, `_running_agents`, and `_agent_graph["nodes"]`. This creates a window where the sub-agent thread is executing but the global registry doesn't know about it yet.

In the normal path (`create_agent` in `agents_graph_actions.py`), `_agent_instances[state.agent_id] = agent` is set *before* `thread.start()`. The reversed order here means that if the sub-agent's first LLM call returns very quickly and triggers a graph lookup (e.g. `view_agent_graph` or `agent_finish`), the node won't exist yet, potentially leading to a `KeyError`.

Move `t.start()` to after the full registration block:

```python
with agents_graph_actions._agents_lock:
    agents_graph_actions._running_agents[agent_id] = t
    agents_graph_actions._agent_instances[agent_id] = agent
    agents_graph_actions._agent_states[agent_id] = state
agents_graph_actions._agent_graph["nodes"][agent_id] = {
    "status": "running",
    "name": state.agent_name,
    "task": state.task,
    "parent_id": state.parent_id,
    "started_at": datetime.now(UTC).isoformat(),
}
t.start()  # start only after full registration
```

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

_{Reviews (2): Last reviewed commit: "fix code-review issues and add 8 new vul..." | Re-trigger Greptile}

[Ahmex000]

2026-03-21.11-02-02.mp4

[Ahmex000]

@greptile-apps