Site 5 (BC at L290): _async_search_mcp (nested in _search_mcp) had:
try:
data = json.loads(res_str)
if isinstance(data, list): return data
elif isinstance(data, dict) and 'results' in data: return data['results']
return []
except:
return []
Body: bare 'except:' + return [] = empty default = SS-style violation.
Migrated to Result[T] via new module-level helper _parse_search_response_result:
- Returns Result(data=parsed_list) on success
- Returns Result(data=None, errors=[ErrorInfo]) on JSON parse failure
- Handles the list/dict/no-results branch logic
The helper is module-level (does not use self) and is placed BEFORE
class RAGEngine to avoid breaking the class definition (a def at column 0
inside a class ends the class prematurely).
Legacy _async_search_mcp delegates to the helper; on Result errors,
returns [] (preserving the original behavior).
Audit: rag_engine BC 1 -> 0; migration-target: 0.
Remaining 4 INTERNAL_RETHROW sites are Pattern 1/3 of the styleguide
(known audit limitation).
index_file had 3 try/except sites with similar patterns:
Site 3 (BC at L247): try: mtime = os.path.getmtime(full_path); except Exception: return
Site 4 (BC at L261): try: with open(full_path, ...) as f: content = f.read(); except Exception: return
Site 6 (SS at L255): try: res = self.collection.get(...); ...; except Exception: pass
Body: broad catch + early return/pass = SS-style violation.
New helpers:
- _get_file_mtime_result(full_path) -> Result[float]
Catches OSError only (specific to file stat failures).
- _check_existing_index_result(file_path, mtime) -> Result[bool]
Catches broad Exception (chromadb collection.get failures vary).
Returns data=True if already indexed (skip), data=False if needs re-indexing.
- _read_file_content_result(full_path) -> Result[str]
Catches (OSError, UnicodeDecodeError) (file I/O + encoding failures).
Legacy index_file calls each helper; on Result errors, returns early
(preserving the original behavior of skipping the file on failure).
Audit: rag_engine BC 3 -> 1 (L341 _async_search_mcp remaining).
SS: 1 -> 0.
Site 2 (BC at L224): _chunk_code had a fallback to text chunking on any
failure:
try:
parser = ASTParser('python')
tree = parser.parse(content)
...
return chunks
except Exception:
return self._chunk_text(content)
Body: broad catch + fallback to a different implementation = empty-default
fallback = SS-style violation.
New helper _chunk_code_result(content, file_path) -> Result[List[str]]:
- Returns Result(data=chunks) on AST parse success
- Returns Result(data=None, errors=[ErrorInfo]) on parse failure
Legacy _chunk_code calls helper; on Result errors, falls back to
_chunk_text (preserving original behavior). The catch logic is in the
legacy, not the helper, so the caller decides the fallback strategy.
Audit: rag_engine BC 4 -> 3.
Site 1 (BC at L33) was:
except Exception as e:
sys.stderr.write(f'FAILED to import sentence_transformers: {e}')
sys.stderr.flush()
raise e
Per TIER1_REVIEW: catch + log + re-raise is Pattern 2 of the styleguide.
The fix is to narrow the except to specific exception types that
sentence_transformers could raise on import (ImportError, AttributeError).
Refactored to:
except (ImportError, AttributeError) as e:
sys.stderr.write(f'FAILED to import sentence_transformers: {e}')
sys.stderr.flush()
raise
The bare 'raise' re-raises the current exception being handled,
preserving the original type and traceback. (Replaces 'raise e' which
raised a specific value but lost the traceback context.)
Audit: rag_engine BC 5 -> 4. RETHROW +1 (the narrowed except is now
classified as Pattern 3 catch+re-raise; strict mode accepts).
Phase 13: rag_engine migration (9 sites: 1 SS + 5 BC + 3 RETHROW).
rag_engine.py is the smallest baseline file. Single phase since 9 sites
fit comfortably.
Migration rules (per TIER1_REVIEW Phase 9 redo):
- SS sites (1): MIGRATE to Result[T] (no logging, no pass, no empty default)
- BC sites (5): narrow to specific types; if body returns structured error
carrier use Heuristic E match; otherwise migrate to Result[T]
- RETHROW sites (3): classify per Pattern 1/2/3; if Pattern 1 fits add
'from e'; if suspicious catch+bare-raise migrate to Result[T]
rag_engine is a RAG subsystem (vector store). Most sites are likely at
the SDK boundary (chromadb, embedding providers). Pattern matches
should be straightforward.
Phase 12: ai_client rethrow classification (6 sites).
Site 1 (L276 _load_credentials): added 'from e' (Pattern 1)
Sites 2+3 (L878+L879 _default_send nested): added 'from None' (Pattern 1)
Site 4 (L1336 _list_anthropic_models): migrated to Result (the broken
'raise ErrorInfo from exc' runtime bug — same pattern as Phase 10 site 1)
Site 5 (L2078 _send inside _send_gemini_cli): added 'from None' (Pattern 1)
Site 6 (L2759 _dashscope_call): added 'from None' (Pattern 1)
KNOWN LIMITATION: the audit script does not have a heuristic for
'raise X from e' or 'from None' (Pattern 1 compliant). The 5 Pattern 1
sites remain classified as INTERNAL_RETHROW ('suspicious but not
violation') in the audit. Strict mode (Phase 14 gate) accepts this.
Adding a Pattern 1 heuristic requires Tier 1 approval per the
conventions ('Never modify audit heuristics without explicit Tier 1
approval'). Documented in the end-of-track report.
Audit state (after Phase 12):
mcp_client: 0 migration-target (Phase 3-8 complete)
ai_client: 7 -> 6 migration-target (5 RETHROW + 0 SS + 0 BC + 0 UNCLEAR)
BC: 0 (Phase 10)
SS: 0 (Phase 11)
RETHROW: 7 -> 6 (one site migrated to Result in Phase 12)
UNCLEAR: 0
COMPLIANT: 33 -> 34 (+1)
rag_engine: 9 migration-target (Phase 13)
Tests: 109 pass (was 97; +12 Phase 12 site/invariant tests).
Site 4 (L1337) had:
try: anthropic = _require_warmed('anthropic'); ... client.models.list() ...
except Exception as exc:
raise _classify_anthropic_error(exc) from exc
BUG: _classify_anthropic_error returns ErrorInfo (a dataclass), NOT
an Exception. 'raise ErrorInfo from exc' would fail at runtime.
Migration per Phase 9 redo precedent: convert to Result[T]. This is
the same fix pattern applied to _list_gemini_models in Phase 10.
New helper _list_anthropic_models_result() -> Result[list[str]]:
- Returns Result(data=sorted_models) on success
- Returns Result(data=[], errors=[_classify_anthropic_error(...)])
on SDK/credentials failure
Legacy _list_anthropic_models returns result.data (preserves signature).
Audit: ai_client RETHROW 5 -> 5 (no change; site 4 was previously
counted as INTERNAL_RETHROW, now classified as INTERNAL_COMPLIANT
since the try/except is gone — the helper has the Result-returning
exception body which matches Heuristic A).
Actually let me verify with audit_summary...
Per styleguide §7.6 Pattern 1: 'catch + convert + raise as different type'
requires 'raise X from e' to preserve the original exception in the
traceback.
Sites updated:
Site 1 (L277 _load_credentials):
except FileNotFoundError as e:
raise FileNotFoundError(f'...') from e
Sites 2+3 (L878+L879 _default_send, nested in run_with_tool_loop):
if not res.ok:
raise res.errors[0].original from None
raise RuntimeError(...) from None
The exceptions come from a Result, not a local except; 'from None'
suppresses the implicit context.
Site 5 (L2061 _send inside _send_gemini_cli):
raise cast(Exception, send_result.errors[0].original) from None
Site 6 (L2742 _dashscope_call):
raise classify_dashscope_error(_dashscope_exception_from_response(resp)) from None
KNOWN LIMITATION: the audit script does not have a heuristic for
'raise X from e' / 'from None' (Pattern 1). The sites remain
INTERNAL_RETHROW in the audit. INTERNAL_RETHROW is 'suspicious but
not violation' (strict mode accepts). Adding a heuristic requires
Tier 1 approval per the conventions.
Audit: ai_client RETHROW 6 -> 5 (site 4 migrated separately; these
4 sites stay as INTERNAL_RETHROW by audit classification but follow
Pattern 1 by styleguide).
Phase 12: ai_client rethrow classification (6 sites).
3 legitimate re-raise patterns from styleguide:
1. Catch + convert + raise as different type (with rom e):
try: json.loads(raw)
except json.JSONDecodeError as e: raise ValueError(f'Invalid JSON: {e}') from e
2. Catch + log + re-raise:
try: do_something()
except Exception as e: logger.exception('failed; will propagate'); raise
3. Catch + cleanup + re-raise (or use try/finally for pure cleanup).
SUSPICIOUS pattern (NOT compliant):
try: do_something()
except Exception: raise
This catches an exception, does nothing with it, and re-raises. The
try/except is dead code; remove it or use Result-based propagation.
Per MUST-DOT-DO #4: 'raise a custom exception class for runtime failures' is forbidden.
Migration rules per Phase 12 plan:
- If site fits Pattern 1/2/3: leave as-is (audit should classify as COMPLIANT)
- If site is SUSPICIOUS (catch + bare raise): MIGRATE to Result[T]
- Do NOT classify as 'suspicious' (= sliming)
- Per-site: test (if migrated), commit
Both classify functions had:
try:
sdk = _require_warmed('xxx')
if isinstance(exc, sdk.SomeException): return ErrorInfo(...)
...
except (ImportError, AttributeError):
pass
# body-string matching fallback
...
Body: bare 'except: pass' = SS violation (silent recovery).
Migration per TIER1_REVIEW directive (per-site decision):
- Initial attempt: _try_warm_sdk(name) -> Any sentinel (None on failure)
- Audit flagged the sentinel helper as UNCLEAR (Heuristic B requires class
method with self.attr assignment; module-level sentinel doesn't match)
- Per Phase 9 redo precedent: migrate to Result instead of adding heuristic
Final approach: _try_warm_sdk_result(name) -> Result[Any]
Returns Result(data=module) on success,
Result(data=None, errors=[ErrorInfo]) on ImportError/AttributeError.
Classify callers check result.ok and use result.data on success.
Audit: ai_client SS 2 -> 0; UNCLEAR 1 -> 0 (after Result migration).
COMPLIANT 32 -> 33.
Site 11 at module level had:
if os.environ.get('SLOP_TOOL_PRESET'):
try:
set_tool_preset(os.environ['SLOP_TOOL_PRESET'])
except Exception:
pass
Body: bare 'except Exception: pass' = SS violation.
Migration: call the _set_tool_preset_result helper from Phase 11 site 5.
The helper returns Result[None]; on error it captures the structured
ErrorInfo. The top-level loader ignores the Result (env-var preset is
optional, errors are not fatal at module load time).
Audit: ai_client SS 3 -> 2.
Both sites 9 (gemini) and 10 (gemini_cli) in get_token_stats had:
try: _ensure_gemini_client()
if _gemini_client:
resp = _gemini_client.models.count_tokens(model=_model, contents=md_content)
total_tokens = cast(int, resp.total_tokens)
except Exception: pass
Body: pass = SS violation.
New helper _count_gemini_tokens_for_stats_result(md_content) -> Result[int]:
- Returns Result(data=token_count) on success
- Returns Result(data=0, errors=[ErrorInfo]) on SDK failure or warmup failure
- Caller treats 0 as 'token count unavailable' and falls back to
character-based estimation
Legacy get_token_stats now uses:
if p in ('gemini', 'gemini_cli'):
total_tokens = _count_gemini_tokens_for_stats_result(md_content).data
(combined both branches into one since the logic was identical)
Audit: ai_client SS 5 -> 3. COMPLIANT 31 -> 32.
Both functions had:
try: ToolPresetManager().load_all() ...
except (OSError, ValueError, AttributeError) as e:
sys.stderr.write(f'[ERROR] Failed to set {preset_name}: {e}')
sys.stderr.flush()
sys.stderr.write is logging = NOT a drain = SS violation per MUST-NOT-DO #6.
New helpers:
- _set_tool_preset_result(preset_name: Optional[str]) -> Result[None]
Empty/None preset short-circuits to Result(data=None).
On failure: Result(data=None, errors=[ErrorInfo]).
- _set_bias_profile_result(profile_name: Optional[str]) -> Result[None]
Same pattern.
Legacy wrappers set the global state (or skip on empty preset) and
delegate to the _result helper. Cache invalidation runs regardless.
Audit: ai_client SS 9 -> 7. COMPLIANT 27 -> 29.
Sites L432 (cleanup) and L450 (reset_session) had:
try: _gemini_client.caches.delete(name=_gemini_cache.name)
except Exception: pass
This is bare 'except: pass' = INTERNAL_SILENT_SWALLOW violation (logging is NOT
a drain; 'pass' is the worst form of silent recovery).
Migration: use existing _delete_gemini_cache_result() helper (added Phase 10).
The helper returns Result[None]; on SDK error logs a warning to comms.
The caller ignores the Result (cleanup is best-effort).
Audit: ai_client SS 11 -> 9.
Phase 11: ai_client silent-swallow (11 sites; was 9, +2 from Phase 9 narrowing set_tool_preset/set_bias_profile).
CRITICAL ANTI-SLIMING RULES (MUST follow):
1. NO narrowing + logging: 'except (NarrowType): logging.error(...)' is a VIOLATION
2. NO empty defaults: 'except (NarrowType): args = {}' is a VIOLATION (sliming)
3. NO pass: 'except: pass' is a VIOLATION (silent)
4. NO traceback.print_exc alone: similar to logging, data is lost
5. logging.error / logger.exception / sys.stderr.write alone: NOT a drain
Per MUST-NOT-DO #6: 'DO NOT catch except Exception and silently swallow.'
Per MUST-NOT-DO #7: 'DO NOT catch except Exception in non-*_result code without conversion to ErrorInfo.'
Per TIER1_REVIEW 2026-06-20 (Phase 9 redo): 'empty default is NOT a drain — the caller must observe the errors.'
Canonical pattern for SS sites:
def _feature_result(...) -> Result[T]:
try:
return Result(data=compute())
except (NarrowType) as e:
return Result(data=<zero>, errors=[ErrorInfo(kind=INTERNAL, message=str(e), source=..., original=e)])
Legacy wrapper preserves original signature; surface errors via Result where possible.
Some sites may not have a clear 'caller' (e.g., _extract_gemini_thoughts is called inline); for these, the _result helper captures the structured error and the legacy function returns the empty data default (preserving current behavior).
All 3 run_tier4_* functions had the same pattern:
try: ... AI call ...
except Exception as e: return '[XXX FAILED] {e}' (or None)
Per TIER1_REVIEW: empty-default return = MIGRATE to Result[T].
New helpers:
- _run_tier4_analysis_result(stderr: str) -> Result[str]
Returns Result(data=analysis) on success, Result(data='', errors=[ErrorInfo])
on SDK failure. Empty stderr short-circuits to Result(data='').
- _run_tier4_patch_callback_result(stderr: str, base_dir: str) -> Result[Optional[str]]
Returns Result(data=patch) on valid diff, Result(data=None) when no
valid diff, Result(data=None, errors=[ErrorInfo]) on SDK failure.
- _run_tier4_patch_generation_result(error: str, file_context: str) -> Result[str]
Returns Result(data=patch) on success, Result(data='', errors=[ErrorInfo])
on SDK failure. Empty error short-circuits to Result(data='').
Legacy wrappers delegate to _result helpers and return result.data,
preserving original signatures (str for sites 7,9; Optional[str] for site 8).
Existing tier4 tests pass (13/13 in test_tier4_patch_generation +
test_tier4_interceptor).
Audit: ai_client BC 3 -> 0. All 9 Phase 10 BC sites migrated.
Site L1990: inner _send(r_idx) in _send_gemini_cli had:
try: resp_data = adapter.send(...)
except Exception as e: events.emit('response_received', {'error': str(e)}); raise
This is Re-Raise Pattern 2 (catch + emit event + raise). Per TIER1_REVIEW,
the migration is to Result[T] because the audit does not yet recognize
events.emit as a structured error carrier.
New helper _send_cli_round_result(r_idx, adapter, payload, ...) -> Result[dict]:
- Emits request_start + [CLI] comms before SDK call
- Returns Result(data=resp_data) on SDK success
- On failure: emits response_received error event + returns Result(errors=[ErrorInfo(original=e)])
Inner _send refactored:
send_result = _send_cli_round_result(r_idx, adapter, payload, ...)
if not send_result.ok:
raise cast(Exception, send_result.errors[0].original)
resp_data = send_result.data
This preserves the original re-raise behavior so the outer
_send_gemini_cli try/except still catches and converts to Result.
Audit: ai_client BC 4 -> 3.
Site L1773: cache.create block in _send_gemini had multiple global side
effects (sets _gemini_cache, _gemini_cache_created_at, _gemini_cached_file_paths,
returns chat_config with cached_content). Except body reset globals on failure.
Per TIER1_REVIEW: logging is NOT a drain. MIGRATE to Result[Any].
New helper _create_gemini_cache_result(sys_instr, tools_decl, file_items) -> Result[Any]:
- Returns Result(data=chat_config) on SDK success (sets globals, logs [CACHE CREATED])
- Returns Result(data=None, errors=[ErrorInfo]) on SDK failure (resets globals,
logs [CACHE FAILED])
- Preserves original semantics: globals set on success, reset on failure
Caller:
cached_config_result = _create_gemini_cache_result(sys_instr, tools_decl, file_items)
if cached_config_result.ok:
chat_config = cached_config_result.data
Audit: ai_client BC 5 -> 4. _send_gemini cache-related BC sites all migrated.
Site L1732: count_tokens block in _send_gemini had:
try: count_resp = _gemini_client.models.count_tokens(...)
... set should_cache based on total_tokens ...
except Exception as e: _append_comms('[COUNT FAILED]')
Per TIER1_REVIEW: logging is NOT a drain. MIGRATE to Result[bool].
New helper _should_cache_gemini_result(sys_instr: str) -> Result[bool]:
- Result(data=True) if token count >= 2048
- Result(data=False) if below threshold + [CACHING SKIPPED] comms note
- Result(data=False, errors=[ErrorInfo]) on SDK failure + [COUNT FAILED] comms
Caller: should_cache = _should_cache_gemini_result(sys_instr).data
Audit: ai_client BC 6 -> 5. Site L1732 (now shifted to L1752) no longer BC.
Sites L1680 (cache.delete on context change) and L1692 (cache.delete on
TTL expiry) had identical patterns:
try: _gemini_client.caches.delete(name=_gemini_cache.name)
except Exception as e: _append_comms('OUT', 'request', {'message': f'[CACHE DELETE WARN] {e}'})
Per TIER1_REVIEW: logging is NOT a drain. MIGRATE to Result[T].
Single helper _delete_gemini_cache_result() -> Result[None]:
- Returns Result(data=None) on success
- Returns Result(data=None, errors=[ErrorInfo]) on SDK failure + logs warning to comms
- Caller (_send_gemini) ignores errors (best-effort cleanup)
Audit: ai_client BC 8 -> 6. Both sites migrated.
The original function had a broken pattern: 'raise _classify_gemini_error(exc)
from exc' which raises an ErrorInfo (not an Exception) — a runtime bug.
Per TIER1_REVIEW 2026-06-20 directive: per-site decision. The body raised a
structured error carrier (ErrorInfo), but the pattern was incorrect (ErrorInfo
is not an Exception). Cleanest fix: full Result[T] migration.
New helper:
- _list_gemini_models_result(api_key: str) -> Result[list[str]]
Returns Result(data=sorted_models) on success, Result(data=[], errors=[ErrorInfo])
on SDK/network failure.
Legacy wrapper:
- _list_gemini_models(api_key: str) -> list[str]
Returns result.data (preserves original signature; callers don't see errors).
Audit: ai_client BC 9 -> 8. Site L1594 (now shifted to L1609 due to helper insertion)
no longer in INTERNAL_BROAD_CATCH.
Phase 10: ai_client Batch B (9 INTERNAL_BROAD_CATCH sites).
Key rules for Phase 10:
- MUST-DO #1: Use Result[T] for any function that can fail at runtime
- MUST-DO #2: Catch SDK exceptions at the boundary, convert to ErrorInfo
- MUST-NOT-DO #6: DO NOT catch except Exception and silently swallow
- MUST-NOT-DO #7: DO NOT catch except Exception in non-*_result code without conversion to ErrorInfo
Canonical BC pattern (lines 540-562):
def _feature_result(self) -> Result[T]:
try:
return Result(data=compute())
except Exception as e:
return Result(data=None, errors=[ErrorInfo(kind=INTERNAL, message=str(e), source=..., original=e)])
Per-site decision process (Tier 1's directive):
- narrow + return ErrorInfo or dict[error]=True: Heuristic E match (already INTERNAL_COMPLIANT)
- narrow + empty default (e.g., args={}): MIGRATE to Result[T]
- broad except Exception: MIGRATE to Result[T] (BOUNDARY_CONVERSION)
- broad + re-raise: classify per Pattern 1/2/3 (Phase 12 territory)
In-depth restoration guide covering:
- Branch state + last 10 commit SHAs
- Phase-by-phase summary (9 of 14 complete)
- Anti-sliming protocol + Heuristic E reference
- Test state (31 baseline + 16 audit heuristics)
- Audit state per file (mcp_client 100%, ai_client 36%, rag_engine 0%)
- Migration pattern template
- TIER1_REVIEW directive verbatim summary
- Reload checklist for post-compact agent
- Conventions (1-space indent, CRLF, no comments, no git restore)
- Remaining 27 ai_client migration-target sites mapped to phases
- Final verification commands for Phase 14
The restored agent after compact should read this first to reorient.
3 empty-default sites per Tier 1 directive (NOT heuristic — empty default
is NOT a drain per error_handling.md:528-531):
1. L394 set_provider (minimax branch): added _set_minimax_provider_result helper.
The helper returns Result[list[str], ErrorInfo] with structured errors.
Legacy set_provider delegates to the helper; falls back to empty key on
failure (preserving original behavior).
2. L716+L723 _execute_tool_calls_concurrently (deepseek + minimax):
added _parse_tool_args_result helper that returns Result[dict, ErrorInfo].
The for-loop accumulates per-call errors into a local file_errors list.
3. L994 _reread_file_items: added _reread_file_items_result helper that
returns Result[tuple, ErrorInfo]. Per TIER1_REVIEW, caller does NOT
check err_item["error"] flag (verified by reading _build_file_diff_text
and the 4 callers), so this site needed full migration (NOT heuristic).
Legacy function delegates to the helper and logs errors to stderr
(operator-visible drain).
All 4 originally-UNCLEAR sites are now compliant:
L332, L355: BOUNDARY_CONVERSION (via existing creates_errorinfo check)
L394, L716, L723, L994: COMPLIANT (via Result-returning migration)
Audit: ai_client UNCLEAR 6 -> 0. Total: 19 INTERNAL_COMPLIANT.
Tests: 51 pass (28 baseline + 16 audit heuristics + 5 ai_client + 2 async_tools).
Heuristic E: narrow + structured error carrier (per TIER1_REVIEW_phase9_dilemma_20260620):
- except (NarrowType): return ErrorInfo(...) -> INTERNAL_COMPLIANT
- except (NarrowType): <item>["error"] = True -> INTERNAL_COMPLIANT
Distinguishes from the empty-default pattern (args = {}, body = ...) which
is explicitly NOT a drain per error_handling.md:528-531.
Refactored L332, L355 except bodies:
Was: except (ValueError, AttributeError): body = exc.response.text
Now: except (ValueError, AttributeError) as e: return ErrorInfo(...)
The function still returns ErrorInfo either way. When JSON parse fails,
we can't classify specific error codes, so we return UNKNOWN with the
original exception preserved (drain: structured ErrorInfo, not lost-default).
Added 2 helper methods:
_has_errorinfo_return(stmts) -> bool
_has_dict_error_true_assign(stmts) -> bool
Tests: 41 pass (28 baseline + 13 audit heuristics including the original 8).
Audit: ai_client UNCLEAR 6 -> 4 (L332+L355 now BOUNDARY_CONVERSION).
Remaining UNCLEAR: L394, L716, L723, L994 (will migrate in subsequent commits).
Tier 1's decision (NOT Tier 2's blanket Option A):
1. Add audit heuristic for narrow + structured error carrier (return ErrorInfo,
or dict[error] = True if caller checks the flag). Handles L332, L355, L994.
2. Migrate 3 empty-default sites to Result[T] (L394 set_provider, L716+L723
_execute_tool_calls_concurrently). Per styleguide:528-531, empty-default
is NOT a drain.
3. Verify L994 caller. If they check err_item[error], heuristic. If not, migrate.
Reasoning: tier 2 conflated 'return ErrorInfo' and 'return empty default' as
both legitimate, but the styleguide distinguishes them. Empty default = sliming.
Phase 10+ continues with per-site decision: is the body returning structured
error (heuristic candidate) or empty default (migrate)?
Tier 2 (autonomous) hit a dilemma in Phase 9:
Plan said: do not change the audit heuristic.
Plan also said: classify-as-suspicious laundering is forbidden.
Reality: 6 of 8 Phase 9 sites migrated via narrowing are now classified as
UNCLEAR by the audit because the existing heuristics don't recognize
their drain patterns (return ErrorInfo, set empty default, err_item dict).
This contradicts the plan's preconditions for completing the track.
Options documented for Tier 1:
A) Add 1-2 audit heuristics (recommended, ~5-10 min work)
B) Full Result[T] migration of 6 sites (~30-60 min work)
C) Defer to Phase 11 (plan-divergent)
No source code changed. Awaiting Tier 1 decision before Phase 10.
Was: except Exception as e (broad)
Now: except (OSError, UnicodeDecodeError) as e
The err_item drain (returned via the refreshed list with error: True flag)
is preserved. Only specific file I/O errors are caught now.
Both deepseek and minimax branches in the tool call dispatcher had:
try: args = json.loads(tool_args_str)
except: args = {}
json.JSONDecodeError is a subclass of ValueError, so narrowed to:
except (ValueError, TypeError): args = {}
This satisfies the BC classification (specific exception types).
Narrowed 3 INTERNAL_BROAD_CATCH sites to specific exception types:
1. set_provider (L394): except Exception -> except (OSError, ValueError)
for the credential loading fallback
2. set_tool_preset (L520): except Exception -> except (OSError, ValueError, AttributeError)
for tool preset loading (sys.stderr.write + flush preserved)
3. set_bias_profile (L537): except Exception -> except (OSError, ValueError, AttributeError)
for bias profile loading (sys.stderr.write + flush preserved)
Sites 4-5 are now narrow+log patterns which the audit will classify as
INTERNAL_SILENT_SWALLOW (a violation per the styleguide's anti-sliming
rule). They will be addressed in Phase 11 (silent-swallow cleanup).
The bare 'except:' in _classify_deepseek_error (L332) and _classify_minimax_error (L355)
was classified as INTERNAL_BROAD_CATCH. Narrowed to 'except (ValueError, AttributeError)'
since the only realistic exceptions from exc.response.json() are JSONDecodeError (subclass of ValueError)
and AttributeError (if exc.response is None or .json() is missing).
Phase 9 = ai_client Batch A: 8 INTERNAL_BROAD_CATCH sites in src/ai_client.py.
ai_client is the AI provider SDK layer (Anthropic/Gemini/DeepSeek/MiniMax).
17 BC sites total (per Phase 1 audit); first 8 sites = Batch A.
The 4 BOUNDARY_SDK sites stay as-is (vendor SDK exceptions are converted).
The 4 INTERNAL_PROGRAMMER_RAISE sites stay as-is (raise AttributeError in
__getattr__ etc.). The 17 INTERNAL_COMPLIANT sites stay as-is.
The 9 INTERNAL_SILENT_SWALLOW and 7 INTERNAL_RETHROW sites are handled in
Phases 11 and 12 respectively.
Target: ai_client BC 17 -> 9 after Batch A.
Three nested helper functions inside _result variants had silent-swallow
or broad-catch patterns that the audit still flagged:
1. py_find_usages_result._search_file (L846):
Was: 'try/except Exception: pass' (silent-swallow per-file read errors)
Now: try/except (OSError, UnicodeDecodeError) as e: errors.append(ErrorInfo(...))
Errors propagated via the parent's Result.errors
2. derive_code_path_result (L957):
Was: 'try/except Exception: continue' (silent-swallow file parse errors)
Now: try/except (SyntaxError, ValueError) as e: file_errors.append(ErrorInfo(...))
Errors propagated via the parent's Result.errors
3. derive_code_path_result._trace (L996):
Was: try/except Exception as e: output.append(f-string with error)
Now: same output.append + ALSO appends ErrorInfo to file_errors
Drain: output appears in the result data string (operator-visible)
All 3 sites now comply with the data-oriented convention.
Audit: mcp_client migration-target sites: 0 (was 3). Categories:
BOUNDARY_CONVERSION: 5, INTERNAL_COMPLIANT: 43
The legacy StdioMCPServer.stop() had 2 'try/except Exception: pass' blocks
(silent-swallow). Migrated to capture errors as ErrorInfo list and surface
them via the [MCP:<name>:stop-warning] drain (print to stdout, consistent
with _read_stderr's existing stderr-drain pattern).
No logging-only or pass-only: errors are accumulated into ErrorInfo with
the original exception preserved. The drain is a visible stdout print,
which is a true drain (operator sees it during shutdown).
Audit: mcp_client INTERNAL_SILENT_SWALLOW 2 -> 0. Total mcp_client migration-target sites: 0.
The legacy code used 'try: rp.relative_to(cwd); return True; except ValueError: pass'
to check path containment. Python 3.9+ has Path.is_relative_to() which returns
bool directly, eliminating the silent-swallow try/except entirely.
This is a NON-SLIMING migration: the function's behavior is unchanged (still
returns True/False), the test of path containment is the same, but the
implementation no longer relies on bare except+pass. No logging added, no
silenced error, just a cleaner API.
Audit: mcp_client INTERNAL_SILENT_SWALLOW 3 -> 2.
Re-read lines 462-540 (The Broad-Except Distinction), lines 625-690 (Re-Raise
Patterns), and the AI Agent Checklist. CRITICAL anti-sliming protocol:
Phase 8 = mcp_client silent-swallow + UNCLEAR (6 sites):
- 5 INTERNAL_SILENT_SWALLOW sites (bare-except or except+pass patterns)
- 1 UNCLEAR site
Plus 3 nested BC cleanup (1 _search_file in py_find_usages_result + 2 trace
in derive_code_path_result).
RULES (anti-sliming):
- NO narrowing+logging (narrow + sys.stderr.write / logging.error = STILL violation)
- NO silent recovery (except: pass = SILENT_SWALLOW violation)
- MUST use full Result[T] propagation up to a true drain point
- Logging is NOT a drain (per user's principle 2026-06-17)
Added web_search_result, fetch_url_result, get_ui_performance_result inside Result Variants region.
The 3 legacy functions now delegate to their _result variants.
Audit: mcp_client BC 8 -> 3 (sites 6,7,8 migrated). Remaining 3 sites are
nested functions (1 in py_find_usages_result._search_file + 2 in derive_code_path_result.trace)
which are inherent to the implementation and will be addressed in Phase 8.
Added derive_code_path_result inside Result Variants region.
Legacy derive_code_path (str) now delegates to it. The nested trace
function is now inside the _result variant; its inner try/except
captures ErrorInfo correctly.
Phase 7 = mcp_client Batch E: 8 more INTERNAL_BROAD_CATCH sites
- L1338 py_get_hierarchy, L1359 py_get_docstring
- L1383 derive_code_path, L1418 trace
- L1452 get_tree
- L1535 web_search, L1561 fetch_url, L1580 get_ui_performance
Target: mcp_client BC 9 -> 1 after Batch E (the _search_file nested try/except
is separate from these 8 Batch E sites; will be classified/fixed in Phase 8).
Phase 5 Batch C (8 INTERNAL_BROAD_CATCH sites in mcp_client.py):
Added _result variants in the Result Variants region:
- ts_cpp_get_definition_result
- ts_cpp_get_signature_result
- ts_cpp_update_definition_result
- py_get_skeleton_result (uses ASTParser)
- py_get_code_outline_result (uses outline_tool, NOT ASTParser)
- py_get_symbol_info_result (returns Result[tuple[str, int]])
- py_get_definition_result (uses ast.parse directly)
- py_update_definition_result (delegates to set_file_slice_result)
Each legacy string-returning function now delegates to its _result variant;
the try/except Exception is REMOVED from the legacy function.
The _result variants for py_* functions use ast.parse directly (matching
the existing implementation pattern). py_get_code_outline_result uses
outline_tool (not ASTParser as originally assumed).
Phase 4 test loosened (BC<=24, total MIG<=72) to allow Batch C overshoot.
Audit: mcp_client BC 24 -> 16. Total MIG 72 -> 64.
Re-read lines 462-540 (The Broad-Except Distinction). Same migration
pattern as Phase 3 Batch A: each legacy string-returning tool function
delegates to its _result variant. The try/except Exception in the
legacy function is REMOVED; the new Result variant captures ErrorInfo
with kind=INTERNAL and the original exception.
Phase 4 = mcp_client Batch B: 8 INTERNAL_BROAD_CATCH sites (lines 473-593)
- L473 get_git_diff
- L492 ts_c_get_skeleton, L509 ts_c_get_code_outline, L523 ts_c_get_definition
- L537 ts_c_get_signature, L555 ts_c_update_definition
- L576 ts_cpp_get_skeleton, L593 ts_cpp_get_code_outline
Target: mcp_client BC 32 -> 24 after Batch B.
Added set_file_slice_result(Result[str]) inside the Result Variants region.
Legacy set_file_slice (str) now delegates to set_file_slice_result.
Audit: mcp_client BC count 33 -> 32 (Batch A complete: -8 sites).
Added get_file_slice_result(Result[str]) inside the Result Variants region.
Legacy get_file_slice (str) now delegates to get_file_slice_result.
Audit: mcp_client BC count 34 -> 33.
Added get_file_summary_result(Result[str]) inside the Result Variants region.
Legacy get_file_summary (str) now delegates to get_file_summary_result.
Audit: mcp_client BC count 35 -> 34.
Added edit_file_result(Result[str]) inside the Result Variants region.
Legacy edit_file (str) now delegates to edit_file_result.
Audit: mcp_client BC count 36 -> 35.
Legacy list_directory (str) now delegates to list_directory_result (Result[str]).
The try/except Exception is REMOVED.
Audit: mcp_client BC count 38 -> 37.
Legacy search_files (str) now delegates to search_files_result (Result[str]).
The try/except Exception in the legacy function is REMOVED; the new Result
variant captures ErrorInfo (kind=INTERNAL with original exception).
Audit: mcp_client BC count 39 -> 38.
Legacy _resolve_and_check (Path|None, str tuple) now delegates to
_resolve_and_check_result (Result[Path]). The try/except Exception in the
legacy function is REMOVED; the new Result variant captures the structured
ErrorInfo (kind=INVALID_INPUT for path errors, kind=PERMISSION for
allowlist denials). Error messages are propagated via ui_message().
Updated tests/test_py_struct_tools.py::test_mcp_dispatch_errors to accept
the new 'permission' ErrorKind string instead of the legacy 'ACCESS DENIED'
substring (the new format is more descriptive).
Audit: mcp_client BC count 40 -> 39.
Re-read in full (989 lines). Key sections reviewed for this track:
- The 5 Patterns (Nil-Sentinel, Zero-Init, Fail Early, AND over OR, Side-Channel)
- Drain Points section (the 5 patterns: HTTP error response, GUI error display,
intentional app termination, telemetry emission, bounded retry)
- The Broad-Except Distinction (broad+log = SILENT_SWALLOW violation)
- Re-Raise Patterns 1/2/3 (catch+convert, catch+log+reraise, catch+cleanup+reraise)
- AI Agent Checklist (5 MUST-DO + 7 MUST-NOT-DO + 3 boundary patterns)
- Rule #0: MUST READ THIS STYLEGUIDE FIRST
- The pre-commit gate (4 audit scripts in --strict mode)
Per Rule #0: this commit message acknowledges the read. The full styleguide
content was reviewed end-to-end before any code work in Phase 0.
Adds the end-of-track artifacts for the tier2_leak_prevention_20260620
fix track:
- docs/reports/TRACK_COMPLETION_tier2_leak_prevention_20260620.md:
Full track completion report following the precedent set by
TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md. Documents
the 4 atomic commits, the 25 default-on tests, the manual
end-to-end verification, the key design decisions (auto-unstage
not exit 1, git rm --cached --force, CRLF handling, specific not
prefix patterns), the known limitations, and the next steps for
the user (push to origin, rebase stale tier-2 branches, re-run
setup on the existing clone, optional CI wiring).
- conductor/tracks/tier2_leak_prevention_20260620/metadata.json:
Track metadata (status=shipped, scope: 5 new files + 1 modified,
25 default-on tests, 5 verification criteria, 5 risk-register
entries, 2 deferred follow-up tracks).
- conductor/tracks/tier2_leak_prevention_20260620/spec.md:
Track spec (background on the 00e5a3f2 offender commit, design
with the 3-layer defense-in-depth, forbidden patterns, tests,
out-of-scope items).
- conductor/tracks/tier2_leak_prevention_20260620/plan.md:
Track plan (4 phases: revert + hook + audit + install; tasks
recorded retroactively per workflow.md "Plan is the source of
truth").
- conductor/tracks/tier2_leak_prevention_20260620/state.toml:
Track state (status=completed, current_phase=complete, 4 phases
with checkpoint SHAs, 16 tasks all completed with commit SHAs).
- conductor/tracks.md: registered as track 6f in the Active
Tracks table; added a "Recently Completed" entry with the
commit-history summary.
Per conductor/workflow.md "End-of-track report" protocol. The
report includes a "Mistake to flag" section about the
`Remove-Item -Recurse -Force` accident during verification, per
the AGENTS.md "Hard ban on destructive commands" rule (which is
specifically about `git restore`/`git checkout`/`git reset`/`git
push` but the lesson generalizes: destructive PowerShell commands
on directories with tracked files require explicit verification
before running).
Initial v3 spec + plan for the major nagent review update. Covers 24 new nagent commits + 2 case-study repos (pep-copt, differentiable-collisions-optc) across 11 clusters. v2.3 historical reviews preserved; v3 is the canonical going forward.
TIER-2 READ conductor/code_styleguides/error_handling.md end-to-end before Phase 13.
Final state:
- All 13 phases completed (checksha recorded)
- All verification flags = true (audit_strict_exits_0,
site_inventory_has_42_rows, drain_plane_render_functions_exist,
silent_swallow_count_zero, rethrow_count_zero, unclear_count_zero,
broad_catch_count_zero)
- batched_suite_11_of_11_pass = false (Tier 3 has 1 known issue:
test_gui2_performance.py measures FPS 28.46 vs 30 threshold; documented
in TRACK_COMPLETION report as a known issue for user review)
- tracks.md updated: sub-track 4 row -> 'shipped 2026-06-20'
Track shipped on the success path. All 42 migration-target sites in
src/gui_2.py resolved.
TIER-2 READ conductor/code_styleguides/error_handling.md end-to-end before Phase 13.
The Phase 3 _render_main_interface_result helper runs every frame.
Returning Result(data=True) allocates a fresh dataclass with empty
errors list every call. At 60 FPS, this is 60 allocations/sec just
for the success path.
Fix: introduce module-level _OK_TRUE and _OK_FALSE singletons
(immutable, no errors list allocation). Hot-path helpers return
_OK_TRUE on success; only the error path allocates a new Result.
This is a micro-optimization that preserves the Result[T] contract
(the helper still returns a Result instance). The convention is
satisfied; the allocation overhead is removed.
Note: test_gui2_performance.py::test_performance_benchmarking
measures ~28.4 FPS vs 30 FPS threshold. The frame time is 0.22ms,
which suggests the bottleneck is vsync/throttling, not Python
overhead. The optimization is a defensive measure, not a fix for
this specific test (which appears to be flaky near the threshold).
The Phase 10 migration of the run() function (L728 INTERNAL_SILENT_SWALLOW)
changed App.run's error drain to set self.controller._last_imgui_assert
to traceback.format_exception(...), which returns a list. But the
existing test test_app_run_imgui_assert_handling.py expects it to be
a string containing 'Missing End'.
Fix: set _last_imgui_assert to str(err.original) if available, else
err.message. The IM_ASSERT message string is what the health endpoint
expects.
TIER-2 READ conductor/code_styleguides/error_handling.md end-to-end before Phase 13.
Regression test: tests/test_app_run_imgui_assert_handling.py
test_app_run_records_degraded_state_on_imgui_assert PASSES after fix.
Three regression-guard tests in tests/test_audit_heuristics.py verify
the new lazy-loading sentinel fallback heuristic (commit f996aa10):
- test_lazy_loading_sentinel_fallback_in_resolve_is_compliant:
L65-style nested try/except with self._cached = _FiledialogStub()
in _resolve (mirrors the actual site in src/gui_2.py:65)
-> expects INTERNAL_COMPLIANT
- test_lazy_loading_sentinel_fallback_in_load_is_compliant:
direct self._cached = _FooStub() in _load
-> expects INTERNAL_COMPLIANT
- test_lazy_loading_sentinel_fallback_in_get_is_compliant:
direct self._cached = _BarStub() in _get (catches AttributeError
after a getattr call)
-> expects INTERNAL_COMPLIANT
These tests follow the existing _make_visitor / _find_handler pattern
established by Phase 7 (BOUNDARY_FASTAPI) and Phase 11 (dunder-method
bare-raise) tests. They lock the heuristic's behavior so future edits
to scripts/audit_exception_handling.py cannot accidentally reclassify
the 2 gui_2.py sites (L65, L69) back to UNCLEAR.
Pre-Phase 12: 3 tests in this file (Phase 7 + Phase 11).
Post-Phase 12: 6 tests. 13/13 tests pass (3 new + 10 existing).
Phase 12 result_migration_gui_2_20260619.
Adds a new heuristic to scripts/audit_exception_handling.py:_try_compliant_pattern
(heuristic B, after heuristic A) that recognizes the canonical lazy-loading
sentinel fallback pattern:
def _resolve(self):
try:
self._cached = getattr(mod, attr_name)
except AttributeError:
sub_mod_name = f'{module_name}.{attr_name}'
try:
self._cached = importlib.import_module(sub_mod_name)
except (ImportError, ModuleNotFoundError):
self._cached = _FiledialogStub()
The heuristic fires when:
- The enclosing function is in LAZY_LOADER_METHOD_NAMES
({_resolve, _load, _get, _try_load}) — the canonical naming
convention for proxy classes that defer a heavy import
- The except body does NOT re-raise
- The except set is in {AttributeError, ImportError, ModuleNotFoundError}
- The except body assigns to a self.<attr> (directly or via nested try)
Sites matching this pattern are classified INTERNAL_COMPLIANT (not
UNCLEAR). The sentinel is a documented graceful-degradation marker
with an 'available: bool = False' flag (or similar) that the UI can
check to detect the stub and offer an alternative path. This is
analogous to the nil-sentinel dataclass (Pattern 1 in error_handling.md).
Per error_handling.md:625-690 (Re-Raise Patterns) and the lazy-loading
pattern guidance, this is NOT silent-sliming. Reclassifies the 2
UNCLEAR sites in src/gui_2.py at L65 and L69 (_LazyModule._resolve).
Pre-Phase 12 baseline: 2 UNCLEAR sites. Post-Phase 12: 0 UNCLEAR.
gui_2.py: V=0, S=0, ?=0, C=56 (was V=0, S=0, ?=2, C=54).
Phase 12 result_migration_gui_2_20260619.
Per AI Agent Checklist Rule #0.
Phase 12 focuses on the 2 UNCLEAR sites in src/gui_2.py at L65, L69.
These are in the _LazyModule._resolve method:
def _resolve(self) -> _Any:
if self._cached is None:
mod = _importlib.import_module(self._module_name)
if self._attr_name is None:
self._cached = mod
else:
try:
self._cached = getattr(mod, self._attr_name)
except AttributeError: # L64
sub_mod_name = f'{self._module_name}.{self._attr_name}'
try:
self._cached = _importlib.import_module(sub_mod_name)
except (ImportError, ModuleNotFoundError): # L68
self._cached = _FiledialogStub()
return self._cached
Per the styleguide, lazy-loading sentinel fallbacks are a legitimate
graceful-degradation pattern. The except body does NOT silently swallow;
it FALLS BACK to a documented sentinel (_FiledialogStub) with an
'available' flag so the UI can detect and offer alternatives. This is
analogous to a nil-sentinel dataclass (Pattern 1 in error_handling.md).
The audit heuristic for 'narrow except + documented sentinel fallback'
does not exist yet. We need to add a heuristic per the
result_migration_review_pass_20260617 pattern.
Plan for Phase 12:
1. Add new heuristic to scripts/audit_exception_handling.py:
except (X, Y): self._cached = <named_sentinel_with_available_flag>
in a method named _resolve/_load/_get -> INTERNAL_COMPLIANT
2. Add regression tests in tests/test_audit_heuristics.py
3. Verify UNCLEAR count drops to 0 for gui_2.py
Five regression-guard tests verify the new dunder-method bare-raise
heuristic in scripts/audit_exception_handling.py:_classify_raise:
- test_bare_raise_attribute_error_in_getattr_is_programmer_raise
- test_bare_raise_name_error_in_getattr_is_programmer_raise
- test_bare_raise_in_setattr_is_programmer_raise
- test_bare_raise_in_delattr_is_programmer_raise
- test_bare_raise_in_getattribute_is_programmer_raise
Each test feeds a minimal source sample through the visitor's
_classify_raise and asserts INTERNAL_PROGRAMMER_RAISE. The tests
cover all 4 dunder methods (__getattr__, __getattribute__,
__setattr__, __delattr__) and both programmer-error exception types
(AttributeError, NameError).
Phase 11 result_migration_gui_2_20260619.
ed