@riddledc/riddle-proof 0.5.11 → 0.5.13

package/README.md

@@ -91,6 +91,13 @@ Set `RIDDLE_PROOF_WORKTREE_ROOT` to choose an explicit location. Set
 `RIDDLE_PROOF_USE_WORKSPACE_WORKTREE_ROOT=1` to keep the previous behavior of
 placing proof worktrees next to the active repository.
 
+When local scratch storage is low, setup prunes stale
+`riddle-proof-*` worktrees from the scratch root before creating the next run.
+This preserves the dependency cache for speed while avoiding old failed runs
+filling `/tmp`. Set `RIDDLE_PROOF_KEEP_SCRATCH_WORKTREES=1` to disable that
+cleanup for debugging, or tune the low-space threshold with
+`RIDDLE_PROOF_MIN_SCRATCH_FREE_MB`.
+
 ## Capture Diagnostics
 
 `@riddledc/riddle-proof/diagnostics` standardizes the evidence contract around

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",

package/runtime/lib/recon.py

@@ -783,6 +783,25 @@ elif plan_history:
         'changes': diff_plan(plan_history[-1], current_plan),
         'reason': 'Resumed recon with the current state inputs.',
     })
+
+capture_hint = s.get('capture_hint') if isinstance(s.get('capture_hint'), dict) else {}
+selected_hint = capture_hint.get('selected') if isinstance(capture_hint.get('selected'), dict) else {}
+if capture_hint.get('applied') and selected_hint:
+    fallback_changes = {}
+    hinted_path = str(selected_hint.get('server_path') or '').strip()
+    hinted_selector = str(selected_hint.get('wait_for_selector') or '').strip()
+    if hinted_path and current_plan.get('target_path') != hinted_path:
+        fallback_changes['server_path'] = {'from': hinted_path, 'to': current_plan.get('target_path')}
+    if hinted_selector and current_plan.get('wait_for_selector') != hinted_selector:
+        fallback_changes['wait_for_selector'] = {'from': hinted_selector, 'to': current_plan.get('wait_for_selector')}
+    if fallback_changes:
+        capture_hint['fallback_triggered'] = True
+        capture_hint['fallback_reason'] = (
+            str(previous_assessment.get('decision') or '').strip() if has_previous_assessment else 'plan_refined'
+        ) or 'plan_refined'
+        capture_hint['fallback_changes'] = fallback_changes
+        s['capture_hint'] = capture_hint
+
 plan_history.append(current_plan)
 
 summary_bits = []

package/runtime/lib/setup.py

@@ -9,6 +9,7 @@ local temp storage by default:
 import json, subprocess as sp, os, sys, shutil, time, tempfile
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from util import load_state, save_state, git, shell_quote
+from util import apply_capture_hint
 
 s = load_state()
 repo = s['repo']
@@ -170,6 +171,113 @@ def resolve_worktree_root(repo_dir):
     return os.path.join(tempfile.gettempdir(), '.riddle-proof-worktrees')
 
 
+def env_flag(name, default=False):
+    raw = os.environ.get(name, '').strip().lower()
+    if raw in ('1', 'true', 'yes', 'on'):
+        return True
+    if raw in ('0', 'false', 'no', 'off'):
+        return False
+    return default
+
+
+def env_int(name, default):
+    raw = os.environ.get(name, '').strip()
+    try:
+        value = int(raw)
+    except Exception:
+        return default
+    return value if value > 0 else default
+
+
+def disk_free_bytes(path):
+    probe = path
+    while probe and not os.path.exists(probe):
+        parent = os.path.dirname(probe)
+        if parent == probe:
+            break
+        probe = parent
+    try:
+        return shutil.disk_usage(probe or tempfile.gettempdir()).free
+    except Exception:
+        return 0
+
+
+def prune_scratch_worktrees(worktree_root, keep_dirs, repo_dir):
+    report = {
+        'requested': True,
+        'worktree_root': worktree_root,
+        'removed': [],
+        'errors': [],
+    }
+    if env_flag('RIDDLE_PROOF_KEEP_SCRATCH_WORKTREES', False):
+        report['skipped'] = 'RIDDLE_PROOF_KEEP_SCRATCH_WORKTREES'
+        return report
+    if not worktree_root:
+        report['skipped'] = 'missing_worktree_root'
+        return report
+
+    root = os.path.abspath(os.path.expanduser(worktree_root))
+    temp_root = os.path.abspath(tempfile.gettempdir())
+    if root in ('/', temp_root) or not root.endswith('.riddle-proof-worktrees'):
+        report['skipped'] = 'unsafe_worktree_root'
+        return report
+    if not os.path.isdir(root):
+        report['skipped'] = 'worktree_root_missing'
+        return report
+
+    min_free_bytes = env_int('RIDDLE_PROOF_MIN_SCRATCH_FREE_MB', 2048) * 1024 * 1024
+    free_before = disk_free_bytes(root)
+    report['free_before_bytes'] = free_before
+    report['min_free_bytes'] = min_free_bytes
+    if free_before >= min_free_bytes:
+        report['skipped'] = 'enough_free_space'
+        return report
+
+    keep = set(os.path.abspath(os.path.expanduser(p)) for p in keep_dirs if p)
+    candidates = []
+    for name in os.listdir(root):
+        if not name.startswith('riddle-proof-'):
+            continue
+        path = os.path.join(root, name)
+        resolved = os.path.abspath(path)
+        if resolved in keep or not os.path.isdir(path):
+            continue
+        try:
+            mtime = os.path.getmtime(path)
+        except Exception:
+            mtime = 0
+        candidates.append((mtime, path))
+    candidates.sort()
+
+    for _, path in candidates:
+        if disk_free_bytes(root) >= min_free_bytes:
+            break
+        removed_by_git = False
+        git_error = ''
+        if repo_dir and os.path.exists(os.path.join(repo_dir, '.git')):
+            remove_result = sp.run(
+                'git worktree remove --force ' + shell_quote(path),
+                shell=True,
+                cwd=repo_dir,
+                capture_output=True,
+                text=True,
+            )
+            removed_by_git = remove_result.returncode == 0
+            if remove_result.returncode != 0 and os.path.exists(path):
+                git_error = (remove_result.stderr or remove_result.stdout or '')[:300]
+        if os.path.exists(path):
+            shutil.rmtree(path, ignore_errors=True)
+        if not os.path.exists(path):
+            report['removed'].append({'path': path, 'via': 'git' if removed_by_git else 'filesystem'})
+        elif git_error:
+            report['errors'].append({'path': path, 'git_error': git_error})
+
+    if repo_dir and os.path.exists(os.path.join(repo_dir, '.git')):
+        git('git worktree prune', repo_dir)
+    report['free_after_bytes'] = disk_free_bytes(root)
+    return report
+
+
 def cleanup_legacy_branch_worktrees(repo_dir, branch_name):
     if not repo_dir or not os.path.exists(os.path.join(repo_dir, '.git')):
         return
@@ -367,9 +475,17 @@ s['branch'] = branch
 s['target_branch'] = target_branch
 s['ship_target_branch'] = target_branch
 s['worktree_root'] = WORKTREE_ROOT
+capture_hint = apply_capture_hint(s)
+if capture_hint and capture_hint.get('applied_fields'):
+    print('Applied last-good capture hint: ' + ', '.join(capture_hint.get('applied_fields') or []))
 save_state(s)
 print('Prepared workspace via ' + setup.get('source', 'workspace_core') + ': ' + repo_dir)
 os.makedirs(WORKTREE_ROOT, exist_ok=True)
+scratch_cleanup = prune_scratch_worktrees(WORKTREE_ROOT, (BEFORE_DIR, AFTER_DIR), repo_dir)
+if scratch_cleanup.get('removed') or scratch_cleanup.get('errors'):
+    print('Scratch cleanup: removed ' + str(len(scratch_cleanup.get('removed') or [])) + ' stale proof worktree(s)')
+s['scratch_cleanup'] = scratch_cleanup
+save_state(s)
 cleanup_legacy_branch_worktrees(repo_dir, base_branch)
 
 # Clean any stale worktrees for this run and the legacy fixed paths

package/runtime/lib/util.py

@@ -1,6 +1,6 @@
 """Shared helpers for Riddle Proof pipeline."""
 
-import json, subprocess as sp, os, shlex, time
+import hashlib, json, os, re, shlex, subprocess as sp, tempfile, time
 from urllib.parse import urljoin
 from urllib.request import urlopen
 
@@ -18,6 +18,8 @@ CAPTURE_ARTIFACT_JSON_LIMIT = 256 * 1024
 _JSON_ARTIFACT_CACHE = {}
 CAPTURE_DIAGNOSTIC_VERSION = 'riddle-proof.capture-diagnostic.v1'
 DEBUG_STRING_LIMIT = 2000
+CAPTURE_HINT_CACHE_VERSION = 'riddle-proof.capture-hints.v1'
+CAPTURE_HINT_CACHE_LIMIT = 12
 SENSITIVE_KEY_FRAGMENTS = (
     'authorization',
     'apikey',
@@ -29,6 +31,14 @@ SENSITIVE_KEY_FRAGMENTS = (
     'secret',
     'token',
 )
+HINT_TOKEN_STOPWORDS = {
+    'about', 'after', 'agent', 'agents', 'around', 'before', 'browser', 'change',
+    'changes', 'clarify', 'component', 'copy', 'debug', 'default', 'evidence',
+    'flow', 'homepage', 'improve', 'just', 'main', 'make', 'need', 'normal',
+    'page', 'proof', 'report', 'results', 'review', 'run', 'screen', 'script',
+    'small', 'status', 'text', 'tiny', 'update', 'user', 'verify', 'visible',
+    'workflow',
+}
 
 
 def load_state():
@@ -41,6 +51,206 @@ def save_state(s):
         json.dump(s, f, indent=2)
 
 
+def request_shape_tokens(state, limit=8):
+    haystack = ' '.join([
+        str(state.get('change_request') or ''),
+        str(state.get('context') or ''),
+        str(state.get('success_criteria') or ''),
+    ]).lower()
+    tokens = []
+    for word in re.findall(r'[a-z0-9]+', haystack):
+        if len(word) < 4 or word in HINT_TOKEN_STOPWORDS or word in tokens:
+            continue
+        tokens.append(word)
+        if len(tokens) >= limit:
+            break
+    return tokens
+
+
+def capture_hint_cache_path(state):
+    repo_key = str(state.get('repo') or state.get('repo_dir') or '').strip()
+    if not repo_key:
+        return ''
+    digest = hashlib.sha1(repo_key.encode('utf-8')).hexdigest()
+    return os.path.join(tempfile.gettempdir(), '.riddle-proof-capture-hints', digest + '.json')
+
+
+def load_capture_hint_cache(state):
+    cache_path = capture_hint_cache_path(state)
+    if not cache_path or not os.path.exists(cache_path):
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    try:
+        with open(cache_path) as f:
+            payload = json.load(f)
+    except Exception:
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    if not isinstance(payload, dict):
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    hints = payload.get('hints') if isinstance(payload.get('hints'), list) else []
+    payload['version'] = CAPTURE_HINT_CACHE_VERSION
+    payload['hints'] = hints
+    return payload, cache_path
+
+
+def select_capture_hint(state):
+    payload, cache_path = load_capture_hint_cache(state)
+    hints = payload.get('hints') or []
+    current_tokens = request_shape_tokens(state)
+    current_mode = str(state.get('verification_mode') or '').strip().lower()
+    scored = []
+    for hint in hints:
+        if not isinstance(hint, dict):
+            continue
+        server_path = str(hint.get('server_path') or '').strip()
+        wait_for_selector = str(hint.get('wait_for_selector') or '').strip()
+        if not server_path and not wait_for_selector:
+            continue
+        hint_mode = str(hint.get('verification_mode') or '').strip().lower()
+        hint_tokens = [
+            str(item).strip().lower()
+            for item in (hint.get('request_tokens') or [])
+            if str(item).strip()
+        ]
+        matched_tokens = [token for token in current_tokens if token in hint_tokens]
+        score = len(matched_tokens) * 3
+        if current_mode and hint_mode == current_mode:
+            score += 2
+        if score <= 0:
+            continue
+        scored.append({
+            'score': score,
+            'matched_tokens': matched_tokens,
+            'selection_reason': 'token_overlap_and_mode' if matched_tokens and current_mode and hint_mode == current_mode else (
+                'token_overlap' if matched_tokens else 'verification_mode_match'
+            ),
+            'hint': hint,
+        })
+
+    if not scored:
+        return None
+
+    scored.sort(
+        key=lambda item: (
+            int(item['score']),
+            str(item['hint'].get('saved_at') or ''),
+        ),
+        reverse=True,
+    )
+    selected = scored[0]
+    return {
+        'cache_path': cache_path,
+        'available_count': len(hints),
+        'score': selected['score'],
+        'matched_tokens': selected['matched_tokens'],
+        'selection_reason': selected['selection_reason'],
+        'hint': selected['hint'],
+    }
+
+
+def apply_capture_hint(state):
+    selected = select_capture_hint(state)
+    if not selected:
+        return None
+
+    hint = selected['hint']
+    applied_fields = []
+    server_path = str(hint.get('server_path') or '').strip()
+    wait_for_selector = str(hint.get('wait_for_selector') or '').strip()
+
+    if server_path and not str(state.get('server_path') or '').strip():
+        state['server_path'] = server_path
+        state['server_path_source'] = 'hint_cache'
+        applied_fields.append('server_path')
+    if wait_for_selector and not str(state.get('wait_for_selector') or '').strip():
+        state['wait_for_selector'] = wait_for_selector
+        state['wait_for_selector_source'] = 'hint_cache'
+        applied_fields.append('wait_for_selector')
+
+    if not applied_fields:
+        return None
+
+    state['capture_hint'] = {
+        'source': 'hint_cache',
+        'cache_path': selected['cache_path'],
+        'applied': True,
+        'applied_fields': applied_fields,
+        'matched_tokens': selected['matched_tokens'],
+        'selection_reason': selected['selection_reason'],
+        'available_count': selected['available_count'],
+        'selected': {
+            'saved_at': str(hint.get('saved_at') or ''),
+            'verification_mode': str(hint.get('verification_mode') or ''),
+            'server_path': server_path,
+            'wait_for_selector': wait_for_selector,
+            'observed_path': str(hint.get('observed_path') or ''),
+            'proof_profile_name': str(hint.get('proof_profile_name') or ''),
+            'request_tokens': hint.get('request_tokens') or [],
+        },
+        'fallback_triggered': False,
+    }
+    return state['capture_hint']
+
+
+def record_successful_capture_hint(state, server_path='', wait_for_selector='', observed_path='', source_stage='verify', success_signal=''):
+    server_path = str(server_path or '').strip()
+    wait_for_selector = str(wait_for_selector or '').strip()
+    if not server_path and not wait_for_selector:
+        return {'status': 'skipped_missing_inputs'}
+
+    payload, cache_path = load_capture_hint_cache(state)
+    hints = payload.get('hints') or []
+    request_tokens = request_shape_tokens(state)
+    entry = {
+        'saved_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+        'verification_mode': str(state.get('verification_mode') or '').strip().lower(),
+        'request_tokens': request_tokens,
+        'request_sample': compact_debug_value(str(state.get('change_request') or '')[:240]),
+        'server_path': server_path,
+        'wait_for_selector': wait_for_selector,
+        'observed_path': str(observed_path or '').strip(),
+        'proof_profile_name': str(((state.get('proof_profile') or {}).get('name')) or '').strip(),
+        'source_stage': str(source_stage or '').strip(),
+        'success_signal': str(success_signal or '').strip(),
+    }
+
+    deduped = []
+    for hint in hints:
+        if not isinstance(hint, dict):
+            continue
+        if (
+            str(hint.get('verification_mode') or '').strip().lower() == entry['verification_mode']
+            and str(hint.get('server_path') or '').strip() == entry['server_path']
+            and str(hint.get('wait_for_selector') or '').strip() == entry['wait_for_selector']
+            and list(hint.get('request_tokens') or []) == entry['request_tokens']
+        ):
+            continue
+        deduped.append(hint)
+
+    next_payload = {
+        'version': CAPTURE_HINT_CACHE_VERSION,
+        'repo': str(state.get('repo') or state.get('repo_dir') or '').strip(),
+        'updated_at': entry['saved_at'],
+        'hints': [entry] + deduped[:CAPTURE_HINT_CACHE_LIMIT - 1],
+    }
+    try:
+        os.makedirs(os.path.dirname(cache_path), exist_ok=True)
+        with open(cache_path, 'w') as f:
+            json.dump(next_payload, f, indent=2)
+    except Exception as exc:
+        return {
+            'status': 'error',
+            'cache_path': cache_path,
+            'error': str(exc)[:240],
+        }
+
+    return {
+        'status': 'saved',
+        'cache_path': cache_path,
+        'entry': entry,
+        'hint_count': len(next_payload['hints']),
+    }
+
+
 def compact_debug_value(value, limit=DEBUG_STRING_LIMIT):
     if isinstance(value, str) and len(value) > limit:
         return value[:limit] + '... [truncated]'

package/runtime/lib/verify.py

@@ -19,6 +19,7 @@ from util import (
     invoke_retry,
     load_state,
     prepare_server_preview,
+    record_successful_capture_hint,
     save_state,
     should_use_static_preview,
     summarize_capture_artifacts,
@@ -1139,6 +1140,16 @@ if proof_evidence_required_for_mode(s.get('verification_mode')):
 
 has_good_evidence = required_baseline_present and after_observation.get('valid') and not proof_evidence_blocker
 
+if has_good_evidence:
+    s['capture_hint_saved'] = record_successful_capture_hint(
+        s,
+        server_path=expected_path or s.get('server_path') or '/',
+        wait_for_selector=s.get('wait_for_selector') or '',
+        observed_path=observed_path,
+        source_stage='verify',
+        success_signal='evidence_captured',
+    )
+
 if has_good_evidence:
     supervisor_request = build_supervisor_assessment_request(s, after_payload, after_observation, required_baseline_present, expected_path, evidence_bundle)
     s['verify_status'] = 'evidence_captured'