12 KiB
12 KiB
RESET STATE UTILITY
Reset or rebuild state for a run. Use when state becomes corrupted or needs to be reconstructed from output files.
USAGE:
/reset-state <run_id> [--mode]
PARAMETERS:
run_id: The run identifier to reset--mode: (Optional) Reset mode:delete,rebuild, orverify(default: verify)
MODES:
verify: Check state integrity without changesrebuild: Reconstruct state from output filesdelete: Completely remove state file (WARNING: irreversible)
EXAMPLES:
# Verify state integrity
/reset-state run_20250310_143022
# Rebuild state from output files
/reset-state run_20250310_143022 --rebuild
# Delete state completely
/reset-state run_20250310_143022 --delete
MODE 1: VERIFY (Default)
Check state consistency without modifications:
import json
import os
from glob import glob
state_file = f".claude/state/{run_id}.json"
if not os.path.exists(state_file):
print(f"ERROR: State file not found: {state_file}")
exit(1)
# Load state
with open(state_file, 'r') as f:
state = json.load(f)
print("VERIFYING STATE CONSISTENCY...")
print("")
# Run all consistency checks
checks = []
# Check 1: Schema validation
required_fields = [
"run_id", "spec_path", "output_dir", "total_count",
"status", "created_at", "updated_at", "completed_iterations",
"iterations", "used_urls", "validation"
]
schema_valid = all(field in state for field in required_fields)
checks.append({
"name": "Schema Validation",
"passed": schema_valid,
"details": "All required fields present" if schema_valid else f"Missing fields"
})
# Check 2: File count
output_dir = state['output_dir']
file_count = len(glob(f"{output_dir}/*")) if os.path.exists(output_dir) else 0
expected_count = state['completed_iterations']
file_check = file_count >= expected_count
checks.append({
"name": "File Count",
"passed": file_check,
"details": f"Expected: >={expected_count}, Actual: {file_count}"
})
# Check 3: Iteration consistency
iteration_count = len([i for i in state['iterations'] if i['status'] == 'completed'])
iteration_check = iteration_count == expected_count
checks.append({
"name": "Iteration Records",
"passed": iteration_check,
"details": f"Expected: {expected_count}, Actual: {iteration_count}"
})
# Check 4: URL uniqueness
total_urls = len(state['used_urls'])
unique_urls = len(set(state['used_urls']))
url_check = total_urls == unique_urls
checks.append({
"name": "URL Uniqueness",
"passed": url_check,
"details": f"Total: {total_urls}, Unique: {unique_urls}"
})
# Check 5: File existence
missing_files = []
for iteration in state['iterations']:
if iteration['status'] == 'completed':
if not os.path.exists(iteration['output_file']):
missing_files.append(iteration['output_file'])
existence_check = len(missing_files) == 0
checks.append({
"name": "File Existence",
"passed": existence_check,
"details": f"Missing: {len(missing_files)} files" if missing_files else "All files exist"
})
# Check 6: Timestamp validity
try:
from datetime import datetime
created = datetime.fromisoformat(state['created_at'].replace('Z', '+00:00'))
updated = datetime.fromisoformat(state['updated_at'].replace('Z', '+00:00'))
timestamp_check = updated >= created
checks.append({
"name": "Timestamp Validity",
"passed": timestamp_check,
"details": "Valid chronology" if timestamp_check else "Updated before created"
})
except:
checks.append({
"name": "Timestamp Validity",
"passed": False,
"details": "Invalid timestamp format"
})
# Display results
for check in checks:
status = "✓ PASS" if check["passed"] else "✗ FAIL"
print(f"{status}: {check['name']}")
print(f" {check['details']}")
print("")
# Compute self-consistency score
consistency_score = sum(c["passed"] for c in checks) / len(checks)
print(f"Consistency Score: {consistency_score:.2f} ({consistency_score * 100:.0f}%)")
print("")
# Recommendations
if consistency_score >= 0.8:
print("STATUS: State is consistent and reliable")
print("ACTION: No action needed")
elif consistency_score >= 0.5:
print("STATUS: State has issues but may be recoverable")
print("ACTION: Consider running with --rebuild to fix")
else:
print("STATUS: State is significantly corrupted")
print("ACTION: Rebuild with --rebuild or delete with --delete")
print("")
MODE 2: REBUILD
Reconstruct state from output directory:
import json
import os
from glob import glob
from datetime import datetime
import hashlib
state_file = f".claude/state/{run_id}.json"
# Load original state or create minimal
if os.path.exists(state_file):
print("Loading original state for reference...")
with open(state_file, 'r') as f:
original_state = json.load(f)
spec_path = original_state.get('spec_path', 'unknown')
output_dir = original_state['output_dir']
total_count = original_state.get('total_count', 'unknown')
else:
print("No original state found. Building from scratch...")
print("Enter required information:")
spec_path = input("Spec path: ")
output_dir = input("Output directory: ")
total_count = input("Total count (or 'infinite'): ")
# Verify output directory exists
if not os.path.exists(output_dir):
print(f"ERROR: Output directory not found: {output_dir}")
exit(1)
print("")
print("REBUILDING STATE FROM OUTPUT DIRECTORY...")
print("")
# Scan output directory
output_files = sorted(glob(f"{output_dir}/*"))
print(f"Found {len(output_files)} files in {output_dir}")
print("")
# Extract iteration numbers and build records
iterations = []
used_urls = set()
for file_path in output_files:
# Try to extract iteration number from filename
filename = os.path.basename(file_path)
# Assume pattern: *_<number>.<ext> or iteration_<number>.<ext>
import re
match = re.search(r'_(\d+)\.[^.]+$', filename)
if match:
iteration_num = int(match.group(1))
else:
# Fallback: use file order
iteration_num = len(iterations) + 1
# Compute file hash for validation
with open(file_path, 'rb') as f:
file_hash = hashlib.sha256(f.read()).hexdigest()[:16]
# Try to extract web URL from file content
web_url = "unknown"
try:
with open(file_path, 'r') as f:
content = f.read(1000) # Read first 1000 chars
# Look for common URL patterns in comments
url_match = re.search(r'https?://[^\s<>"]+', content)
if url_match:
web_url = url_match.group(0)
used_urls.add(web_url)
except:
pass
# Get file modification time
mtime = os.path.getmtime(file_path)
completed_at = datetime.fromtimestamp(mtime).isoformat() + 'Z'
iterations.append({
"number": iteration_num,
"status": "completed",
"output_file": file_path,
"web_url": web_url,
"started_at": completed_at, # Approximate
"completed_at": completed_at,
"validation_hash": file_hash,
"metadata": {"rebuilt": True}
})
# Sort by iteration number
iterations.sort(key=lambda x: x['number'])
# Rebuild state structure
rebuilt_state = {
"run_id": run_id,
"spec_path": spec_path,
"output_dir": output_dir,
"total_count": total_count,
"url_strategy_path": original_state.get('url_strategy_path') if 'original_state' in locals() else None,
"status": "paused", # Safe default
"created_at": iterations[0]['completed_at'] if iterations else datetime.now().isoformat() + 'Z',
"updated_at": iterations[-1]['completed_at'] if iterations else datetime.now().isoformat() + 'Z',
"completed_iterations": len(iterations),
"failed_iterations": 0,
"iterations": iterations,
"used_urls": list(used_urls),
"validation": {
"last_check": datetime.now().isoformat() + 'Z',
"consistency_score": 1.0, # Freshly rebuilt
"issues": [],
"rebuilt": True
}
}
# Backup original if exists
if os.path.exists(state_file):
backup_file = f"{state_file}.backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
os.rename(state_file, backup_file)
print(f"Original state backed up to: {backup_file}")
# Write rebuilt state
with open(state_file, 'w') as f:
json.dump(rebuilt_state, f, indent=2)
print(f"State rebuilt successfully!")
print(f" Iterations: {len(iterations)}")
print(f" URLs discovered: {len(used_urls)}")
print(f" State file: {state_file}")
print("")
print("Verifying rebuilt state...")
print("")
# Run verification on rebuilt state
# (Re-run MODE 1 verification logic)
MODE 3: DELETE
Completely remove state file:
import os
from datetime import datetime
state_file = f".claude/state/{run_id}.json"
if not os.path.exists(state_file):
print(f"State file not found: {state_file}")
exit(0)
# Load state for summary
with open(state_file, 'r') as f:
state = json.load(f)
print("WARNING: You are about to DELETE the following state:")
print("")
print(f" Run ID: {state['run_id']}")
print(f" Spec: {state['spec_path']}")
print(f" Output Dir: {state['output_dir']}")
print(f" Iterations: {state['completed_iterations']}")
print(f" Created: {state['created_at']}")
print("")
print("This action is IRREVERSIBLE.")
print("Output files will NOT be deleted, only state tracking.")
print("")
response = input("Type 'DELETE' to confirm: ")
if response == "DELETE":
# Backup before deletion
backup_file = f"{state_file}.deleted_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
os.rename(state_file, backup_file)
print(f"State deleted.")
print(f"Backup saved to: {backup_file}")
print("")
print("To completely remove: rm {backup_file}")
else:
print("Deletion cancelled.")
SELF-CONSISTENCY VALIDATION:
All modes apply self-consistency principle:
Verify Mode:
- Samples 6 independent validation approaches
- Uses majority voting for consistency score
- Multiple checks ensure comprehensive validation
Rebuild Mode:
- Cross-validates rebuilt state against filesystem
- Verifies file hashes for integrity
- Re-runs full verification after rebuild
Delete Mode:
- Creates backup before deletion
- Provides detailed confirmation
- Enables recovery if needed
COMMON USE CASES:
Case 1: State-File Mismatch
Problem: Manual file deletions created inconsistency
Solution: /reset-state <run_id> --rebuild
Result: State reconstructed from actual files
Case 2: Corruption Investigation
Problem: Uncertain if state is reliable
Solution: /reset-state <run_id> --verify
Result: Detailed consistency report
Case 3: Clean Slate
Problem: Want to restart with same run_id
Solution: /reset-state <run_id> --delete
Result: State removed, can create new run
Case 4: URL List Corruption
Problem: Duplicate URLs in state
Solution: /reset-state <run_id> --rebuild
Result: URLs re-extracted from files, deduplicated
SAFETY FEATURES:
Backup Protection:
- Original state always backed up before changes
- Backup includes timestamp
- Can restore from backup if needed
Confirmation Required:
- Delete mode requires explicit confirmation
- User sees summary before deletion
- Can cancel at any point
Non-Destructive:
- Never deletes output files
- Only modifies state tracking
- Rebuild can be re-run if needed
Verification:
- All modes validate their results
- Self-consistency checks applied
- Clear reporting of issues
TROUBLESHOOTING:
Rebuild produces wrong iteration count:
Check filename patterns in output directory
Verify iteration numbers in filenames
Consider manual state editing
Verify shows low score but rebuild fails:
Output directory may be corrupted too
Check file permissions
Inspect sample output files manually
Delete backup grows large:
Old backups can be manually removed
Check .claude/state/*.backup_* files
Delete old backups: rm .claude/state/*.backup_*
NOTES:
- Always run verify before rebuild
- Rebuild is best-effort based on filesystem
- Some metadata may be lost in rebuild (e.g., exact timing)
- Delete provides recovery window via backup
- Self-consistency score indicates reliability