| name | clean-run-state |
| description | Remove stale run-state files left behind by a crashed or abruptly terminated threat-model assessment. Refuses to clean when an active run is still holding the lock. Use when the Claude Code UI shows the threat-modeling skill as "scanning" forever after a session crash. |
You are cleaning orphaned assessment run-state. This skill is not a
threat-modeling run — it touches no source code, spawns no agents, and
writes no threat model artifacts. It only removes the transient run-state
files listed below.
--help — inline help (early exit)
If the user's arguments contain --help or -h, print this block verbatim and exit.
/appsec-advisor:clean-run-state — Remove stale assessment run-state files.
USAGE
/appsec-advisor:clean-run-state [--repo <path>] [--output <path>] [--force] [--dry-run] [--json]
FLAGS
--repo <path> Repository to clean (default: current working dir)
--output <path> Output directory to clean (default: <repo>/docs/security)
--force Clean even when an active run is detected (dangerous —
will kill the other session's lock; use only when you
are certain the other process is dead)
--dry-run Report what would be cleaned without removing anything
--json Emit the result as machine-readable JSON
WHAT IS CLEANED
.appsec-lock PID lock file
.appsec-checkpoint phase= status= timestamp= line
.phase-epoch Unix-timestamp anchor used by phase timers
.session-agent-map hook session tracking
WHAT IS PRESERVED
threat-model.md (your completed threat model)
threat-model.yaml (canonical data)
threat-model.sarif.json (if present)
.fragments/ (composer input set)
.appsec-cache/ (incremental baseline cache)
.agent-run.log (audit trail)
.hook-events.log (audit trail)
All other files (this skill only touches the four files above)
WHEN TO USE
* The Claude Code UI shows the threat-modeling skill as "scanning" but no
claude process is actually running.
* /appsec-advisor:status reports a run in progress from an old session.
* A ~/appsec-advisor:create-threat-model invocation bails out with
LOCK_BLOCKED and you've verified the other session is dead.
The skill is safe to invoke at any time — if no stale state exists, it
reports "clean" and exits 0.
After printing the help block, exit. Do not proceed.
Step 1 — Parse arguments
Recognized flags (and the values consumed by --repo / --output):
--repo <path> --output <path> --force --dry-run --json --help | -h
Parse these and set REPO_ROOT, OUTPUT_DIR, FORCE_MODE, DRY_RUN_MODE,
JSON_MODE.
- Default
REPO_ROOT to the current working directory.
- Default
OUTPUT_DIR to $REPO_ROOT/docs/security.
--repo <path> overrides REPO_ROOT.--output <path> overrides OUTPUT_DIR.
Reject unknown arguments (hard fail)
If the invocation contains any token that is not one of the recognized
flags above — or is not the value consumed by --repo / --output — DO NOT
proceed. Do not resolve CLAUDE_PLUGIN_ROOT, do not invoke the helper, do
not touch any state file. Print the following block verbatim to stderr,
substituting <TOKEN> with the first unknown token, then exit with status
2:
Error: unknown argument '<TOKEN>'
/appsec-advisor:clean-run-state accepts only:
--repo <path> Repository to clean (default: current working dir)
--output <path> Output directory to clean (default: <repo>/docs/security)
--force Clean even when an active run is detected
--dry-run Report what would be cleaned without removing anything
--json Emit the result as machine-readable JSON
--help, -h Show full help and exit
Run `/appsec-advisor:clean-run-state --help` for details.
A flag that takes a value (e.g. --repo or --output) counts as unknown
when its value is missing — treat the flag itself as the offending token in
that case. Repeated occurrences of the same flag are allowed; the last value
wins.
Step 2 — Resolve CLAUDE_PLUGIN_ROOT
if [ -z "$CLAUDE_PLUGIN_ROOT" ]; then
CLAUDE_PLUGIN_ROOT=$(find /root /home /opt -maxdepth 6 \
-path "*/appsec-advisor/skills/clean-run-state/SKILL.md" \
2>/dev/null | head -1 | xargs -r dirname | xargs -r dirname | xargs -r dirname)
fi
export CLAUDE_PLUGIN_ROOT
if [ -z "$CLAUDE_PLUGIN_ROOT" ] || [ ! -d "$CLAUDE_PLUGIN_ROOT" ]; then
echo "Error: CLAUDE_PLUGIN_ROOT could not be resolved." >&2
exit 2
fi
Step 3 — Dispatch to the helper
Branch on the --dry-run / --force flags:
Dry-run (report only, no mutation)
ARGS="$OUTPUT_DIR"
[ "$JSON_MODE" = "true" ] && ARGS="$ARGS --json"
python3 "$CLAUDE_PLUGIN_ROOT/scripts/check_state.py" $ARGS
The script's exit code propagates — 0 when clean / active, 1 when stale
or orphan state was detected. In dry-run mode we never mutate, so exit 1
is informational ("run without --dry-run to clean").
Normal cleanup (default)
ARGS="$OUTPUT_DIR --clean"
[ "$JSON_MODE" = "true" ] && ARGS="$ARGS --json"
python3 "$CLAUDE_PLUGIN_ROOT/scripts/check_state.py" $ARGS
EXIT=$?
Exit-code handling:
0 — cleaned successfully (or there was nothing to clean).2 — refused because an active run holds the lock. Report the situation
to the user and suggest --force if they are certain the other session
is dead.- Any other code — propagate as-is.
Forced cleanup (--force)
When --force is passed, the skill removes the lock even when a live PID
is detected. This is dangerous — it invalidates any still-running assessment.
The skill MUST:
- Print a warning line:
⚠ --force requested — removing lock regardless of PID liveness.
Any still-running assessment will lose its lock and may crash.
- Invoke the cleaner with the
--force flag supplemented by a direct
rm -f on the lock files. The Python helper refuses to clean active
state by design (the state machine is the guarantor of correctness);
the skill layer owns the escape hatch:
rm -f "$OUTPUT_DIR/.appsec-lock"
rm -f "$OUTPUT_DIR/.appsec-checkpoint"
rm -f "$OUTPUT_DIR/.phase-epoch"
rm -f "$OUTPUT_DIR/.session-agent-map"
- Re-run the inspector (without
--clean) so the user sees the final
state:
python3 "$CLAUDE_PLUGIN_ROOT/scripts/check_state.py" "$OUTPUT_DIR"
Step 4 — (No step 4)
The helper's output is the skill's output. Exit with the helper's exit code
(propagated from Step 3). Do not add commentary beyond the --force warning
described above.
