refactor: decompose cadis-core/lib.rs by extracting helper modules by DeryFerd · Pull Request #59 · Growth-Circle/cadis

DeryFerd · 2026-05-09T20:00:34Z

Problem Statement

The cadis-core/src/lib.rs file has grown to over 14,500 lines, making it increasingly difficult to navigate and maintain. The file contains a mix of high-level orchestration logic alongside numerous helper functions for worker lifecycle management, approval workflows, and session handling. This monolithic structure creates several issues:

Cognitive load: Developers must scroll through thousands of lines to find relevant code
Compilation time: Large single files can slow down incremental compilation
Code review difficulty: PRs touching different concerns become harder to review
Maintenance risk: Accidental coupling between unrelated subsystems

Solution Architecture

This PR extracts three groups of helper functions into dedicated modules, each focused on a specific domain:

Module Structure

crates/cadis-core/src/
├── lib.rs                    (main orchestration, ~14,300 lines after extraction)
├── worker_helpers.rs         (worker lifecycle and command handling)
├── approval_helpers.rs       (approval workflow utilities)
└── session_helpers.rs        (agent session lifecycle helpers)

Domain Separation

worker_helpers.rs - Encapsulates worker-related concerns:

Worker state transitions and lifecycle event mapping
Worktree state management and cleanup policies
Worker command execution, failure handling, and artifact generation
Worker status string representations and terminal state detection

approval_helpers.rs - Encapsulates approval workflow concerns:

Approval expiration checking
Conversion between store records and protocol payloads

session_helpers.rs - Encapsulates agent session lifecycle concerns:

Agent session event lifecycle mapping
Session status labeling for display/logging
Terminal session state detection

Implementation Details

Extraction Strategy

The extraction was performed as a pure code move operation:

Functions were moved verbatim to their respective modules
All imports were preserved and adjusted for the new module locations
Helper functions were made pub to maintain accessibility from lib.rs
Module declarations and use statements were added to lib.rs

No Functional Changes

This is a zero-functional-change refactor:

All function signatures remain identical
All logic remains unchanged
All tests continue to pass without modification
The public API of cadis-core is unaffected

Line Count Impact

Before: lib.rs = 14,586 lines
After: lib.rs = 14,364 lines (reduced by 222 lines)
New modules: worker_helpers.rs (184 lines), approval_helpers.rs (40 lines), session_helpers.rs (60 lines)
Total: Same code, better organized

Benefits

Improved Navigation: Developers can quickly jump to the relevant helper module instead of searching through a monolithic file
Better Compilation: Smaller files enable better incremental compilation performance
Clearer Separation of Concerns: Each module has a single, well-defined responsibility
Easier Code Review: PRs touching worker helpers can be reviewed in isolation from session or approval logic
Future Refactoring: Smaller modules are easier to further decompose or reorganize if needed

Migration Notes

No migration is required. This is an internal refactoring that does not affect:

Public APIs
External dependencies
Configuration files
Database schemas
Protocol definitions

All existing code continues to work without modification.

Next Steps

Future refactoring opportunities (not included in this PR):

Consider extracting the orchestrator logic into its own module
Evaluate whether workspace helpers could also be extracted
Assess if voice-related functions warrant a dedicated module
Consider splitting the remaining lib.rs into logical subsystems (e.g., runtime, state, handlers)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eed4462039

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-09T20:02:30Z

+use cadis_protocol::{
+    WorkerCommandFailure, WorkerCommandReport, WorkerEventPayload, WorkerLifecycleEventKind,
+    WorkerState, WorkerWorktreeCleanupPolicy, WorkerWorktreeState,


Keep worker helper types in cadis-core

This refactor moves worker helpers into a child module but imports WorkerCommandFailure, WorkerCommandReport, and WorkerLifecycleEventKind from cadis_protocol; these were not protocol exports (the command structs are still private in lib.rs, and the lifecycle enum was removed from there). With worker_helpers now included by lib.rs, cadis-core cannot resolve these imports, so the crate fails to compile before any worker functionality can run.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a8254ba3c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-09T21:11:24Z

            self.debug_events.push_back(DebugEvent {
                timestamp: Instant::now(),
                label,
-                detail: String::new(),
            });


Restore DebugEvent detail initialization

When the HUD compiles this event path, this struct literal is now missing the required detail field that is still defined on DebugEvent in crates/cadis-hud/src/types.rs. Since there is no Default update or struct change in this commit, building cadis-hud fails as soon as this literal is type-checked.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-09T21:11:24Z

+        "stdout": report.stdout,
+        "stderr": report.stderr,
+        "timed_out": report.timed_out,
+        "duration_ms": report.duration_ms,


Preserve worker command report metadata

The extracted JSON helper no longer matches the original report artifact schema: the previous implementation included status, stdout_truncated, stderr_truncated, and timeout_ms, but this replacement swaps in duration_ms and omits the fields that tell consumers whether validation passed, timed out, or had truncated output. For workers that run validation commands, the generated validation_command artifact will lose the status and truncation metadata needed to interpret the captured stdout/stderr.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8b1dfebd6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-10T06:36:37Z

+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct WorkerRecord {


Reuse the existing worker record type

This helper module declares a new private WorkerRecord instead of using the WorkerRecord that lib.rs still stores and passes into helpers. In the current diff, calls such as worker_terminal_worktree_state(worker, status) and plan_worker_terminal_worktree(worker, ...) pass lib.rs's WorkerRecord, so the extracted helper signatures now expect a different nominal type and cadis-core cannot type-check until these helpers operate on the original record type (or stay in the same module).

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-10T06:36:37Z

+    if !report.stdout.is_empty() {
+        logs.push(format!("STDOUT:\n{}", report.stdout));


Preserve bounded worker command logs

When a validation command produces stdout/stderr, this replacement pushes the entire captured output with a new STDOUT:/STDERR: prefix instead of using the previous bounded command stdout:/command stderr: log format with truncation markers. For long validation output, worker log deltas can now exceed WORKER_COMMAND_LOG_LIMIT_BYTES and lose the truncation signal that the existing worker log path/tests in lib.rs expect.

Useful? React with 👍 / 👎.

…ers.rs

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 83cf4be8e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-10T07:10:51Z

+    let mut summary = String::new();
+    summary.push_str(&format!("**Command**: `{}`\n\n", report.command));
+    summary.push_str(&format!(
+        "**Exit Code**: {}\n\n",
+        report.exit_code.map(|c| c.to_string()).unwrap_or_else(|| "None".to_string())
+    ));
+    if report.timed_out {
+        summary.push_str("**Status**: Timed out\n\n");


Preserve validation summary status

For workers that run a validation command, write_worker_artifacts appends this markdown into the summary artifact. This rewrite starts directly with the command/exit code and only emits a status for timeouts, so normal passed/failed validation summaries no longer contain the ## Daemon Validation section or an unconditional Status: passed/failed line that existing summary consumers/tests use to identify the validation result. Restore the old section header and status line for all command outcomes.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9554fafa09

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-10T07:33:12Z

+    if !report.stderr.is_empty() {
+        logs.push(format!("STDERR:\n{}", report.stderr));
+    }
+    logs


Restore worker command completion logs

When the validation command produces no stdout or stderr, this now returns an empty log list, so execute_worker_command emits only the earlier “command started” delta and never the completion/status delta. This is the normal path for a clean default git status --short worker command, and the existing worker lifecycle test in crates/cadis-core/src/lib.rs expects command finished: status=passed exit_code=Some(0) to be present so clients can observe that daemon validation finished successfully.

Useful? React with 👍 / 👎.

refactor: decompose cadis-core/lib.rs by extracting helper modules

eed4462

chatgpt-codex-connector Bot reviewed May 9, 2026

View reviewed changes

DeryFerd added 3 commits May 10, 2026 03:46

fix truncate_output cfg test and debug event

bf393f1

fix formatting in helper modules

427d7e1

fix extra blank lines in lib.rs

7a8254b

chatgpt-codex-connector Bot reviewed May 9, 2026

View reviewed changes

define missing types in worker_helpers.rs and remove unused imports

c8b1dfe

chatgpt-codex-connector Bot reviewed May 10, 2026

View reviewed changes

DeryFerd added 4 commits May 10, 2026 13:39

fix import formatting in lib.rs

652ea75

fix type conflicts by importing from lib.rs instead of duplicating types

a18b195

fix formatting in worker_helpers.rs imports

18833f9

fix struct field mismatches and Option<i32> formatting in worker_help…

83cf4be

…ers.rs

chatgpt-codex-connector Bot reviewed May 10, 2026

View reviewed changes

DeryFerd added 4 commits May 10, 2026 14:11

fix formatting in worker_helpers.rs

c404230

fix missing imports and remove unused import in worker_helpers.rs

4c19b61

fix import formatting in worker_helpers.rs

02a925e

fix dead code warnings and make WorkerLifecycleEventKind public

9554faf

chatgpt-codex-connector Bot reviewed May 10, 2026

View reviewed changes

fix missing detail field in cadis-hud DebugEvent initialization

896f23a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: decompose cadis-core/lib.rs by extracting helper modules#59

refactor: decompose cadis-core/lib.rs by extracting helper modules#59
DeryFerd wants to merge 14 commits into
Growth-Circle:mainfrom
DeryFerd:refactor/decompose-cadis-core-lib

DeryFerd commented May 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		if !report.stdout.is_empty() {
		logs.push(format!("STDOUT:\n{}", report.stdout));

Conversation

DeryFerd commented May 9, 2026

Problem Statement

Solution Architecture

Module Structure

Domain Separation

Implementation Details

Extraction Strategy

No Functional Changes

Line Count Impact

Benefits

Migration Notes

Next Steps

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant