[repository-quality] Repository Quality Improvement Report - Compiler Panic Containment

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Compiler Panic Containment ("BUG:" Exemption Loophole)

Analysis Date: 2026-10-02
Focus Area: Compiler Panic Containment
Strategy Type: Custom
Custom Area: Yes — the panicinlibrarycode linter is CI-enabled, but a message-prefix exemption plus no top-level recover() in the native compile path means invariant panics crash gh aw compile with a raw stack trace.

Executive Summary

pkg/workflow contains 11 production panic() calls that bypass panicinlibrarycode. Most are exempt only because the message starts with "BUG:" (panicMessageStartsWithBUG in pkg/linters/panic-in-library-code/panic-in-library-code.go). The linter therefore cannot tell a real build-time invariant from a panic reachable from user input.

Several of these sit on the per-workflow compile path: mustGetAllowedDomainsForEngineWithModel (domains.go:691, called from universal_llm_consumer_engine.go:295, pi_engine.go:423, behavior_defined_engine.go:734), claude_tools.go:142, and cache_config.go:46. Their safety depends on validation running earlier. The native CLI has no recover() around compile. The only compile-level recovery is in cmd/gh-aw-wasm/compile_recovery.go. In a 299-workflow batch compile, one bad invariant aborts the whole run with a Go stack trace and no workflow file context.

Recommendation: convert the reachable panics to returned errors, and add a recovery boundary that reports the workflow path. Then tighten the linter so the BUG: prefix alone no longer exempts a panic.

Full Analysis Report

Focus Area: Compiler Panic Containment

Current State Assessment

Metrics Collected:

Metric	Value	Status
Production panic( in pkg/cmd (excluding linter testdata)	~11 in pkg/workflow, plus actionpins (3), parser/virtual_fs (2), testutil (2)	⚠️
panicinlibrarycode enabled in cgo.yml	Yes	✅
Exemptions in linter	sync.Once, init(), BUG: prefix, documented panic contract	⚠️
recover() around native compile of each workflow	None (only cmd/gh-aw-wasm/compile_recovery.go)	❌
Panics reachable from the per-workflow compile path	≥4	❌
os.Exit in library code	0 outside linter testdata	✅

Findings

Strengths

• The os.Exit/log.Fatal linters are clean.
• Init-time panics are mostly in sync.Once, init, or embedded-data loaders. A failure there points at a broken build, not user input.
• The cacheMemoryDirFor panic is documented and tested (cache_id_validation_test.go:88).

Areas for Improvement

• High: domains.go:691 panics on model errors that "should have been caught by validation". It has three callers, one of which (behavior_defined_engine.go:729) panics again at its own call site. A custom engine definition or a model alias edge case that bypasses validateModelAliasMap kills the process.
• Medium: claude_tools.go:142 panics on a tool-map shape check. It only logs "ERROR" first, so it should return an error.
• Medium: The BUG: prefix exemption makes the linter unable to flag the panics above. It also encourages mislabelling.
• Medium: There is no recovery boundary in compileSpecificFiles or the equivalent. A panic aborts remaining workflows and loses the file name.
• Low: cacheMemoryDirFor is called from 8 sites in cache_memory.go and sandbox.go. Validation is at parse time, so the risk is small, but the string-returning API forces a panic.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Add per-workflow panic recovery to native compile

Priority: High
Estimated Effort: Small
Focus Area: Compiler Panic Containment

Description: Wrap the per-file compile in the CLI so a panic becomes a normal compile error that names the workflow file, instead of aborting the whole batch with a stack trace. Reuse the approach in cmd/gh-aw-wasm/compile_recovery.go.

Acceptance Criteria:

• A panic during one workflow's compile is reported as an error that includes the file path.
• Other workflows continue to compile and the exit code is non-zero.
• A unit test injects a panic and asserts both behaviours.

Code Region: pkg/cli/compile_*.go (compileSpecificFiles / single-file compile), cmd/gh-aw-wasm/compile_recovery.go

Add a recovery boundary around compiling each workflow in pkg/cli (see cmd/gh-aw-wasm/compile_recovery.go for the existing pattern). Convert a recovered panic to an error naming the workflow path, log the stack with pkg/logger, and continue the batch. Add a test that injects a panic. Run make fmt and the pkg/cli unit tests.

---

Task 2: Convert reachable invariant panics to returned errors

Priority: High
Estimated Effort: Medium
Focus Area: Compiler Panic Containment

Description: Replace mustGetAllowedDomainsForEngineWithModel (callers in universal_llm_consumer_engine.go, pi_engine.go, behavior_defined_engine.go) with error propagation. Make computeAllowedClaudeToolsString return an error instead of panicking.

Acceptance Criteria:

• No panic remains in domains.go or claude_tools.go.
• Callers return the error up the compile path with workflow context.
• Tests cover an invalid model and a claude section in tools.

Code Region: pkg/workflow/domains.go, pkg/workflow/claude_tools.go, pkg/workflow/behavior_defined_engine.go, pkg/workflow/pi_engine.go, pkg/workflow/universal_llm_consumer_engine.go

Remove the panics in pkg/workflow/domains.go:691 and claude_tools.go:142 by returning errors and updating all callers (behavior_defined_engine.go, pi_engine.go, universal_llm_consumer_engine.go). Follow the error-messages skill. Add tests. Run make fmt and go test ./pkg/workflow/.

---

Task 3: Tighten the panicinlibrarycode BUG: exemption

Priority: Medium
Estimated Effort: Small
Focus Area: Compiler Panic Containment

Description: Stop panicMessageStartsWithBUG from exempting a panic by message alone. Require a (nolint/redacted):panicinlibrarycode // <reason> justification instead, or limit the exemption to init, sync.Once, or package-level initialization contexts. Update the linter testdata.

Acceptance Criteria:

• The BUG: prefix alone no longer suppresses the diagnostic.
• Remaining legitimate panics carry a justified nolint or sit in an exempt context.
• The linter tests and make golint-custom pass.

Code Region: pkg/linters/panic-in-library-code/, pkg/workflow/*.go panic sites

Modify pkg/linters/panic-in-library-code so a "BUG:" message prefix no longer exempts a panic. Update testdata and add justified (nolint/redacted):panicinlibrarycode comments to the legitimate remaining panics (see the go-linters skill). Run the linter tests and make golint-custom.

---

Task 4: Make cacheMemoryDirFor non-panicking

Priority: Low
Estimated Effort: Small
Focus Area: Compiler Panic Containment

Description: Return (string, error) from cacheMemoryDirFor. Update the 8 callers in cache_memory.go and sandbox.go, and change TestCacheMemoryDirFor_InvalidIDPanics to assert an error.

Acceptance Criteria:

• No panic in cache_config.go.
• Callers propagate the error.
• Tests updated and passing.

Code Region: pkg/workflow/cache_config.go:37, pkg/workflow/cache_memory.go, pkg/workflow/sandbox.go:340

Change cacheMemoryDirFor to return (string, error) instead of panicking; update all callers and the test in cache_id_validation_test.go. Run make fmt and go test ./pkg/workflow/.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-09-28	Skill doc drift (3rd audit)	Custom	Y	22 stale JS path refs
2026-09-29	Uncancellable subprocess exec	Custom	Y	93 exec.Command calls
2026-09-30	Frontmatter reference coverage	Custom	Y	11/68 fields undocumented

---

🎯 Recommendations

Immediate Actions (This Week)

1. Add per-workflow panic recovery — Priority: High
2. Convert domains/claude_tools panics to errors — Priority: High

Short-term Actions (This Month)

1. Tighten the linter's BUG: exemption — Priority: Medium

Long-term Actions (This Quarter)

1. Remove remaining production panics where practical — Priority: Low

---

📈 Success Metrics

• Panics reachable from the compile path: ≥4 → 0
• Panic exemptions that rely only on the BUG: prefix: ~6 → 0

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 4 weeks

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-10-03 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 29.6 AIC · ⌖ 7.66 AIC · ⊞ 9.7K · ◷

• expires on Oct 3, 2026, 5:05 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-03T13:05:33.412Z.

Closed by Workflow