[sergo] Sergo Report: Exported-Symbol Dead-Code + Magic-Literal Duplication - 2026-05-13

[github-actions[bot]]

Executive Summary

Run 8 of Sergo combined two fresh axes that had not been touched in the prior seven runs: (a) a dead-code audit across the nine utility sub-packages in pkg/ using find_referencing_symbols-style usage counts, and (b) a magic-literal duplication scan focused on file-permission octals and HTTP-client timeouts.

The dead-code half came back clean — all nine utility packages (sliceutil, typeutil, jsonutil, stringutil, semverutil, envutil, timeutil, repoutil, actionpins) showed healthy multi-site usage of their exported APIs. The magic-literal half was much more productive: 57 file-mode octal literals and 4 repeated HTTP-client timeouts are scattered across pkg/ with no centralized constants, and the codebase itself already contains evidence (pkg/workflow/awf_helpers.go:182) that the team knows 0644 leaks secrets — yet 16 other prod sites still write at 0644 with no policy justification.

Two high-value, well-scoped issues filed: #aw_sg8a1 (file-permission constants) and #aw_sg8a2 (HTTP-client timeout). Success score: 8/10 — strong findings, but the dead-code half produced no actionable output, so coverage is asymmetric.

Serena Tools Update

Tools Snapshot

• Total Tools Available: 23 (unchanged from Run 7)
• New Tools Since Last Run: None
• Removed Tools: None
• Modified Tools: None

Tool Capabilities Used Today

• activate_project — bootstrap Go project state
• get_symbols_overview — enumerate exported functions/types in 9 utility packages
• find_symbol (with name_path_pattern + include_body) — fetch SafeUint64ToInt and SafeUintToInt bodies
• Grep — primary tool for usage counts (per Run 7 lesson: find_symbol broad queries take 70s+, Grep is faster for plain name lookups)

Gotcha reconfirmed

find_symbol rejects --name_path outright; must use --name_path_pattern (Pydantic validation error otherwise). Cached.

Strategy Selection

Cached Reuse Component (50%)

Adapted from: Run 7 (switch-statement-complexity-plus-exported-api-usage-audit, 9/10).

• Why reused: Run 7's exported-API-usage audit via find_referencing_symbols was the highest-leverage half of that run — it surfaced the 8-way dispatch-table issue (#aw_sg7a1) that Run 7's own switch-axis missed.
• Modifications: Run 7 only audited safe-outputs handler symbols. Today, I extended the audit to nine utility packages to test the dual hypothesis that (a) utility packages accumulate orphaned exported helpers, and (b) some helpers might be candidates for unexport. Counts via Grep (faster than Serena for plain name lookups per cached gotcha).
• Result: All nine packages had healthy 5+ external sites of usage. Only borderline case: envutil.GetIntFromEnv used at 1 prod site (pkg/cli/logs_orchestrator.go) — not worth filing.

New Exploration Component (50%)

Novel approach: Magic-literal duplication scan — a fresh axis untouched in Runs 1-7.

• Tools: Grep with regex over file-mode octals (os\.(MkdirAll|WriteFile|OpenFile|Mkdir|Chmod)\([^)]*0[0-7]+) and HTTP-client timeout literals (http\.Client\{Timeout:).
• Hypothesis: Repos that grow organically accumulate hardcoded literals where named constants would be safer and more auditable. pkg/constants/ already exists with a healthy Default* naming convention, so consolidation is mechanical.
• Result: Confirmed strongly. See findings below.

Combined Rationale

The dead-code half acts as a defensive sweep (confirming the utility surface area is well-utilized — useful signal even when finding nothing), while the magic-literal half is offensive search against a high-leverage refactor opportunity. They share a unifying theme: inventory the surface of pkg/, then check whether each entry has a clear home. Dead-code finds entries without consumers; magic literals find consumers without an entry.

Analysis Execution

Codebase Context

• Total pkg/ Go files (non-test): 784
• Subpackages: 24 (pkg/actionpins, pkg/agentdrain, pkg/cli, pkg/console, pkg/constants, pkg/envutil, pkg/fileutil, pkg/gitutil, pkg/jsonutil, pkg/logger, pkg/parser, pkg/repoutil, pkg/semverutil, pkg/sliceutil, pkg/stats, pkg/stringutil, pkg/styles, pkg/testutil, pkg/timeutil, pkg/tty, pkg/types, pkg/typeutil, pkg/workflow)
• Focus areas: 9 utility packages for dead-code; entire pkg/ for magic literals

Findings Summary

• Total Issues Found: 9
• Critical: 0
• High: 2 (file perms, HTTP timeout)
• Medium: 1 (mcp_inspect_mcp.go:253 missing Timeout — folded into #aw_sg8a2)
• Low: 6 (envutil.GetIntFromEnv borderline single-site; SafeUint vs SafeUint64 trivial wrapper; expression_patterns.go has 21 already-centralized patterns — confirming the team uses this pattern; markdown_security_scanner.go has 28 well-centralized regexes; misc)

Detailed Findings

High Priority

Finding 1 — File-permission octal magic literals (57 prod sites) [Issue #aw_sg8a1]

57 raw octal literals across pkg/ non-test code in os.MkdirAll/os.WriteFile/os.OpenFile/os.Chmod calls. Breakdown:

Mode	Count	Typical use
0755	27	dir creation
0644	16	general file writes
0600	10	security-sensitive files
0750	4	security-sensitive dirs

No FilePerm* or DirPerm* constants exist in pkg/constants/. The codebase already shows policy awareness — pkg/workflow/awf_helpers.go:182 explicitly comments that the default 0644 would leave "secrets (e.g. MCP gateway tokens) world-readable on the runner host" — yet 16 other prod sites still use 0644 with no policy justification. Inconsistency examples:

• pkg/cli/includes.go:351, :455, pkg/cli/resources.go:207 write downloaded remote content at 0600 (good) — but pkg/parser/import_cache.go:130 writes equivalent remote-fetched cache content at 0644.
• pkg/cli/audit.go:749 uses 0750 for audit output, while pkg/cli/copilot_setup.go:186 uses 0755 for a workflows dir.

Finding 2 — HTTP-client default timeout literal 30 * time.Second (4 prod sites) [Issue #aw_sg8a2]

pkg/parser/remote_fetch.go:521
pkg/cli/mcp_registry.go:50
pkg/cli/deps_security.go:139
pkg/cli/agent_download.go:45

All use the same literal for the same conceptual purpose (network call with a generous best-effort timeout) but with no centralized constant — even though pkg/constants/constants.go already groups other defaults like DefaultAgenticWorkflowTimeout, DefaultToolTimeout, DefaultMCPStartupTimeout.

Bonus: pkg/cli/mcp_inspect_mcp.go:253 constructs an &http.Client{...} with custom-header Transport but omits Timeout entirely. Whether the wrapping mark3labs MCP transport applies its own deadline is unverified in the issue's validation steps.

Medium Priority (folded into Finding 2)

Missing HTTP-client timeout at pkg/cli/mcp_inspect_mcp.go:253 — included as a validation step inside #aw_sg8a2 rather than a separate issue, because the fix depends on auditing transport behavior.

Low Priority Observations

• pkg/typeutil/SafeUintToInt is a 1-line wrapper around SafeUint64ToInt. Both are used. Trivial.
• pkg/envutil/GetIntFromEnv used at 1 prod site. Acceptable — utility function still appropriate.
• pkg/workflow/markdown_security_scanner.go has 28 regexp.MustCompile calls — all package-level vars, well-organized. No action.
• pkg/workflow/expression_patterns.go has 21 regexp.MustCompile calls — package-level, named, documented. Confirms the team uses package-level regex var patterns idiomatically.
• 59 prod-side N * time.{Second,Minute,Hour,Millisecond} literals total. Outside the four HTTP-client cluster, most are context-specific (polling delays, cache TTLs) and don't warrant centralization.
• 8 http.Client{...} constructor sites total in prod (4 with explicit 30s Timeout, 2 with named constants/short literals, 2 inspector-class with custom transports).

Improvement Tasks Generated

Task 1: Centralize file-permission constants in pkg/constants/constants.go (filed as #aw_sg8a1)

Severity: High (security + maintainability)
Affected Files: 57 prod sites in pkg/
Risk: Inconsistent permission choices for sensitive content; a future contributor copy-pastes 0644 for a file that should be 0600.

Recommendation: Add four typed fs.FileMode constants (FilePermSensitive=0o600, FilePermPublic=0o644, DirPermSensitive=0o750, DirPermPublic=0o755) with docstrings stating the policy. Replace all 57 sites, making the sensitive/public choice explicit at the call site.

Task 2: Centralize default HTTP-client timeout (filed as #aw_sg8a2)

Severity: Medium
Affected Files: 4 explicit prod sites + 1 audit (mcp_inspect_mcp.go:253)
Risk: Drift if a future contributor changes the timeout in one place but not the others; hidden indefinite-hang risk in the missing-Timeout site.

Recommendation: Add constants.DefaultHTTPClientTimeout = 30 * time.Second and replace four sites. Audit the inspector-class site to confirm whether it should also adopt the default.

Success Metrics

This Run

• Findings Generated: 9 (2 high, 1 medium folded, 6 low)
• Tasks Created: 2 (intentionally below max-3 — both halves of the strategy had to produce; dead-code half came back clean)
• Files Analyzed: 9 utility packages plus full-repo magic-literal scan
• Success Score: 8/10

Score Reasoning

• Findings Quality (3/4): Two strong, actionable issues with security implications; one is straightforwardly mechanical (HTTP timeout).
• Coverage (3/3): Both 50% halves were executed in full. Dead-code half audited 9 packages; magic-literal half ran across all 784 prod files.
• Task Generation (2/3): Only 2 tasks instead of 3 — the dead-code half didn't surface anything worth filing. Honest result rather than padding.

Historical Context

Strategy Performance Trend

Run	Strategy	Score
1	error-handling-and-interface-design	7
2	deep-error-analysis-plus-symbol-naming	8
3	constructor-consistency-plus-type-safety	8
4	concurrency-safety-and-resource-lifecycle	9
5	function-complexity-and-long-function-hot-spots	9
6	parameter-list-systematic-scan-plus-deep-nesting	9
7	switch-statement-complexity-plus-exported-api-usage-audit	9
8	exported-symbol-dead-code-plus-magic-literal-duplication	8

Cumulative Statistics

• Total Runs: 8
• Total Findings: 78
• Total Tasks Generated: 23
• Average Success Score: 8.4 / 10
• Most Successful Strategy Cluster: Complexity-and-structural (Runs 4-7, all 9/10)

Recommendations

Immediate Actions

1. Tackle #aw_sg8a1 (file perms) — high security leverage; mechanical replacement with one-line judgment per site.
2. Tackle #aw_sg8a2 (HTTP timeout) — small effort, prevents future drift, includes a real bug-audit step at mcp_inspect_mcp.go:253.

Long-term Improvements

Magic-literal scanning is high-yield because the codebase already has the infrastructure for centralization (pkg/constants/ package, Default* naming, fs.FileMode-friendly Go API). Future Sergo runs could productize this as a recurring axis: regex for shared literals like file modes, network timeouts, retry counts, default ports, magic UUIDs, and known prefixes (e.g. "/tmp/gh-aw/" appears as a literal multiple times in pkg/constants itself).

Next Run Preview

Suggested Focus Areas for Run 9

• Cached side: Extend the magic-literal axis to string-literal duplication — repeated identifier-keys, default ports, magic prefixes (e.g. gh-aw, /tmp/gh-aw/..., action names). Use the same Grep-driven approach.
• New side: Interface satisfaction audit — use Serena find_symbol on every interface in pkg/ and verify each implementing type actually exists and is reachable. Untouched in Runs 1-8. Combine with error sentinel inventory (errors.Is/errors.As site count vs. exported error variables).

Strategy Evolution

The Run-8 result reinforces a heuristic: fresh axes pay off more than incremental extensions of cached strategies. The 50% cached half produced 0 issues today; the 50% new half produced 2. The next run should consider weighting slightly toward novel exploration (60/40) when prior cached strategies have been thoroughly mined.

---

Generated by Sergo - The Serena Go Expert
Run ID: §25779206526
Strategy: exported-symbol-dead-code-plus-magic-literal-duplication

Generated by Sergo - Serena Go Expert · ● 20.4M · ◷

• expires on May 14, 2026, 5:06 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Sergo - Serena Go Expert.

A newer discussion is available at Discussion #32058.