SOW-0047: reduce adapter tailer complexity

[ktsaou]

Summary

• Split the adapter tailer event loop, flush path, metadata repair, deferral state, watch handling, transcript reconstruction, and parser decode path into focused helpers.
• Preserved runtime behavior with focused parser/tailer tests, direct transcript path aliasing coverage, fuzz seeds, and benchmark guard coverage.
• Recorded the implementation evidence, validation runs, and review convergence in the active SOW.

Validation

• ./scripts/gates.sh passed in 552s after final review convergence.
• Local Codacy Analysis CLI reported 0 issues across the changed adapter files.
• Independent review converged with no actionable findings remaining.

---

Summary by cubic

Refactors the Claude Code adapter to split the tailer and parser into focused helpers, reducing complexity while keeping behavior and performance unchanged. Adds targeted tests, expanded fuzz seeds, and benchmark guard integration to prevent regressions.

• Refactors
  • Moved JSONL decode into parser_decode.go (including parseLine and envelope/record helpers) and trimmed parser.go.
  • Decomposed tailing into helpers: tailer_loop.go (event loop), tailer_flush.go (flush + deferral), tailer_events.go (fsnotify event classification), tailer_watch.go (dir watch and dirty marking), tailer_meta.go (meta repair), tailer_transcript.go (transcript reconstruction), and tailer_deferral.go (deferral state).
  • Simplified tailer.go by removing inlined logic and delegating to the new helpers.
  • Updated benchmarks/tests to use newTailFlush(...).flushDirty(...) and added focused tests (deferral, helpers, parser) with expanded fuzz seeds and transcript aliasing coverage.

^{Written for commit eff7cf9. Summary will update on new commits.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 149 complexity · -29 duplication

Metric	Results
Complexity	149
Duplication	-29

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[cubic-dev-ai]

1 issue found across 17 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/adapters/claude_code/tailer_loop.go">

<violation number="1" location="internal/adapters/claude_code/tailer_loop.go:161">
P1: Tail swallows catch-up discovery failures instead of returning them, so a fatal root/discovery error is reported via OnError but not surfaced to the caller.</violation>
</file>

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Tail swallows catch-up discovery failures instead of returning them, so a fatal root/discovery error is reported via OnError but not surfaced to the caller.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At internal/adapters/claude_code/tailer_loop.go, line 161:

<comment>Tail swallows catch-up discovery failures instead of returning them, so a fatal root/discovery error is reported via OnError but not surfaced to the caller.</comment>

<file context>
@@ -0,0 +1,217 @@
+	if rt.dirty.any() {
+		resetDebounce(rt.debounce)
+	}
+	return nil
+}
+
</file context>