feat(config): configurable agent preflight timeout

[Mitch515]

Adds StoredConfig.preflightTimeoutMs (ms, 0 = no timeout) and uses it for agent preflight checks in setup, doctor, run --verify, and create-prd --chat. This prevents slow/large models from failing verification due to the previous hardcoded 30s timeout.

Summary by CodeRabbit

Release Notes

• New Features
  • Added configurable preflight timeout setting that can be customised during setup and in configuration files. Project-level settings override global defaults. This replaces the previous hardcoded 30-second timeout and applies to all agent preflight checks, allowing you to optimise timeout behaviour for your workflow.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

@QMTCHL is attempting to deploy a commit to the plgeek Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Warning

Rate limit exceeded

@subsy has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 22 minutes and 54 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

The PR introduces a configurable preflight timeout feature throughout the system by adding a new preflightTimeoutMs field to stored configuration, threading it through the agent-loading mechanism, and updating command handlers to use configured timeouts instead of hardcoded values.

Changes

Cohort / File(s)	Summary
Agent loading refactor src/commands/create-prd.tsx	Modified getAgent() to return LoadedAgent object containing both agent and storedConfig instead of agent alone; updated runChatMode to extract and use storedConfig for preflight timeout configuration
Command preflight timeout configuration src/commands/doctor.ts, src/commands/run.tsx	Updated preflight calls to use configurable storedConfig.preflightTimeoutMs with fallback to 30000ms, replacing hardcoded timeout values
Configuration schema and types src/config/schema.ts, src/config/types.ts, src/config/index.ts	Added optional preflightTimeoutMs: number field to StoredConfig with non-negative integer validation; implemented merge logic for project-level config overrides
Configuration testing src/config/index.test.ts, src/config/schema.test.ts	Added validation test coverage for new preflightTimeoutMs field, including negative value rejection, zero allowance, and project override precedence
Setup system extension src/setup/types.ts, src/setup/wizard.ts	Extended SetupAnswers and wizard to collect preflight timeout from user during setup with agent-specific defaults; wired value into stored configuration persistence

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Wizard as Setup Wizard
    participant Config as StoredConfig
    participant GetAgent as getAgent()
    participant Command as Command (run/doctor)
    participant Agent as Agent Preflight

    User->>Wizard: Run setup wizard
    Wizard->>User: Prompt for preflight timeout (ms)
    User->>Wizard: Provide timeout value
    Wizard->>Config: Save preflightTimeoutMs to StoredConfig
    
    User->>Command: Execute command (run/doctor/create-prd)
    Command->>GetAgent: Request agent
    GetAgent->>Config: Load StoredConfig
    GetAgent-->>Command: Return LoadedAgent {agent, storedConfig}
    
    Command->>Agent: Call preflight with storedConfig.preflightTimeoutMs
    Agent-->>Command: Return preflight result
    Command->>User: Display result

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related PRs

• PR #130: Implements the preflight system and integrates preflight checks into the same command flows (create-prd, run, doctor) that this PR modifies to consume the configurable timeout.
• PR #119: Follows the same pattern of adding a new top-level StoredConfig field and updating configuration merge logic to propagate it through the system.
• PR #194: Modifies overlapping code paths in src/commands/create-prd.tsx, particularly the getAgent and runChatMode functions affected by this refactor.

Poem

A rabbit hops through config lanes, 🐰
Where timeouts dance in millisecond refrains,
No more hardcoded thirty thousand wait,
Each agent picks its preflight fate—
Configuration blooms, and speed's our gain! ⚡

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(config): configurable agent preflight timeout' directly and accurately summarises the main change—introducing a configurable preflight timeout setting instead of a hardcoded value.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[subsy]

@Mitch515 Nice work....A few things I'd like addressed:

1. LoadedAgent adds unnecessary coupling

getAgent() was a clean function that returned an agent. Bundling storedConfig into its return type makes it responsible for two things. Since loadStoredConfig is already imported in create-prd.tsx, just call it directly in runChatMode() - same as doctor.ts and run.tsx already do. This keeps getAgent() single-purpose and avoids the new interface entirely.

2. Add a max bound to the schema

preflightTimeoutMs: z.number().int().min(0).optional(),

iterationDelay has .max(300000). This field should have .max(3600000) (matching the wizard's cap) to prevent nonsensical values from hand-edited config files.

3. Remove the wizard prompt

Most users won't need to change this - the 30s default works for nearly all agents. Adding another numeric prompt increases setup friction for everyone to solve a niche problem. Instead, drop it from the wizard and leave it as an advanced option users can set manually in config.toml. The fallback of ?? 30000 at each call site already handles the undefined case cleanly.

Cheers!

[subsy]

@Mitch515 is this still an issue on later versions of ralph-tui ? I implemented some other fixes in recent versions that should have addressed the underlying issue.