feat: add server_url_override config for tmux integration

[simoncrypta]

Summary

• Adds server_url_override configuration option to tmux integration for overriding auto-detected server URLs
• Fixes TLS certificate errors when opencode binds to VPN/Tailscale IPs by allowing users to force localhost
• Adds comprehensive URL validation at config parse time and runtime with safe fallbacks

Changes

• Added server_url_override field to TmuxConfigSchema with z.preprocess() to handle empty strings/null as undefined
• Updated TmuxSessionManager to validate URLs and check for port '0', falling back safely on invalid URLs
• Updated shared TmuxConfig type in src/plugin/types.ts to include server_url_override?: string
• Updated plugin config initialization in index.ts to pass through the new option

Screenshots

N/A - Configuration/feature change without UI

Testing

# Build verification
bun build src/config/schema/tmux.ts --target bun --format esm
bun build src/features/tmux-subagent/manager.ts --target bun --format esm
bun build src/index.ts --target bun --format esm
bun build src/plugin/types.ts --target bun --format esm

Test Cases:

• server_url_override: "http://localhost:4096" - Valid URL, uses localhost
• server_url_override: "https://example.com:8080" - Valid HTTPS URL with port
• server_url_override: "not-a-url" - Invalid URL, fails config validation
• server_url_override: "" - Empty string, treated as not provided (via preprocess)
• server_url_override: null - Null value, treated as not provided (via preprocess)
• server_url_override: "http://localhost:0" - Port 0, falls back to default URL
• Without server_url_override set - Uses existing auto-detection logic

Related Issues

Addresses issue where tmux integration fails when opencode auto-binds to VPN/Tailscale IPs (e.g., 100.77.163.81:4096) instead of localhost, causing TLS certificate errors during health checks.

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

2 issues found across 3 files

Confidence score: 3/5

• There is a concrete regression risk: malformed server_url_override values are not being validated early, so they can pass config parsing and later crash tmux health checks.
• Both issues are medium severity (6/10) with high confidence (9/10), which suggests real user-facing instability unless URL validation is added at assignment/parsing time.
• Pay close attention to src/config/schema/tmux.ts and src/features/tmux-subagent/manager.ts - missing URL validation for server_url_override can turn bad config into runtime failures instead of safe fallback behavior.

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="src/config/schema/tmux.ts">

<violation number="1" location="src/config/schema/tmux.ts:29">
P2: Validate `server_url_override` as a real URL so malformed config values fail during config parsing instead of crashing tmux health checks.</violation>
</file>

<file name="src/features/tmux-subagent/manager.ts">

<violation number="1" location="src/features/tmux-subagent/manager.ts:82">
P2: Validate `server_url_override` before assigning it; malformed values now throw in the tmux health check instead of falling back safely.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[simoncrypta]

I have read the CLA Document and I hereby sign the CLA

[simoncrypta]

@cubic-dev-ai re-review please - I have addressed the URL validation issues by:

1. Changed schema validation from z.string().optional() to z.string().url().optional() for config-time URL validation

2. Added runtime URL validation in manager.ts using new URL() with try-catch, falling back to default behavior on invalid URLs

Both issues should now be resolved.

[cubic-dev-ai]

@cubic-dev-ai re-review please - I have addressed the URL validation issues by:

1. Changed schema validation from z.string().optional() to z.string().url().optional() for config-time URL validation

2. Added runtime URL validation in manager.ts using new URL() with try-catch, falling back to default behavior on invalid URLs
   ...

@simoncrypta I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

3 issues found across 3 files

Confidence score: 3/5

• Schema in src/config/schema/tmux.ts still rejects ""/null, so documented "treat as not provided" cases can fail at config parse time, which is user-facing.
• src/features/tmux-subagent/manager.ts accepts http://localhost:0; without the port === '0' guard, health checks and opencode attach will target port 0 and the pane never starts.
• Given the concrete runtime/config impacts above, this change carries some risk and merits a careful check before merging.
• Pay close attention to src/config/schema/tmux.ts, src/features/tmux-subagent/manager.ts, src/index.ts - config validation, port guard, and shared type wiring.

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="src/features/tmux-subagent/manager.ts">

<violation number="1" location="src/features/tmux-subagent/manager.ts:83">
P2: Apply the existing `port === '0'` guard to `server_url_override`. Right now `http://localhost:0` is accepted, but health checks and `opencode attach` will target port 0 and the pane never starts.</violation>
</file>

<file name="src/index.ts">

<violation number="1" location="src/index.ts:54">
P2: Update the shared `TmuxConfig` type as well; this new field is currently untyped through `createManagers`.</violation>
</file>

<file name="src/config/schema/tmux.ts">

<violation number="1" location="src/config/schema/tmux.ts:29">
P2: This schema still rejects `""` and `null`, so the documented "treat as not provided" cases now fail at config parse time.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[simoncrypta]

@cubic-dev-ai re-review please - all 3 issues have been addressed:

1. manager.ts:83 - Added guard for :

2. plugin/types.ts - Added to the shared type so it's properly typed through

3. schema.ts:29 - Added to handle empty strings and null values:

All test cases now pass.

[cubic-dev-ai]

@cubic-dev-ai re-review please - all 3 issues have been addressed:

1. manager.ts:83 - Added guard for :

...

@simoncrypta I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Auto-approved: Safe addition of a configuration option with robust URL validation and fallback logic. Preserves existing behavior when the override is not used.}