jeo-code 0.8.9 → 0.8.11

package/CHANGELOG.md

@@ -6,6 +6,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.8.11] - 2026-07-08
+_"프롬프트 라우팅 동작이 Error: Unable to connect. Is the computer able to access the url? Error: Was there a typo in the url or port? 와 같은 메시지 남기고 동작안하는데 원인을 파악하고 근본문제해결하자" — traced the raw, provider-less connection error to two compounding gaps. (1) `describeProvider` reports local providers (ollama/lmstudio) as `ready: true` UNCONDITIONALLY — "keyless" only means no credential is required, never that the server is actually reachable — so the routing veto gate (which exists precisely to keep a misconfigured routing target from making a turn worse than routing being off) had no way to catch a `routing.tiers`/`roles` pin to a downed local server. (2) Bun's fetch/undici throws a bare `Error("Unable to connect. Is the computer able to access the url?")` with `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable host — no HTTP status, no provider name, no URL — and this fell through every existing error classifier (`defaultRetryable`, `friendlyProviderError`) to reach the user completely unfiltered._
+
+### Fixed
+- **Local-provider reachability veto gate** (`src/commands/launch.ts`, `src/ai/model-discovery.ts`) — new `isLocalProviderReachable()` performs a short-timeout (1500ms) live probe against ollama/lmstudio before routing commits to a pinned local model. An unreachable server now vetoes the route (falls back to the session/default model, same `warnOnce` pattern as the existing credential/servability veto branches) instead of routing into a turn that would fail mid-call. Cloud providers never reach this branch — their existing credential/servability checks are sufficient.
+- **Provider + base URL context on connection failures** (`src/util/retry.ts`, `src/ai/model-manager.ts`) — new `ConnectionContextError` wraps a raw `isConnectionError` failure (Bun `ConnectionRefused` / Node `ECONNREFUSED`/`ENOTFOUND`/`EHOSTUNREACH`/`EAI_AGAIN`) with the resolved provider and effective base URL, threaded through `resolveCall`'s `Resolved` type and applied at both `call()` and `stream()` in `createModelManager()` — covers the residual case where routing was NOT engaged (e.g. an explicit `/model ollama/...` pin) and a connection failure still needs to reach the user with useful context.
+- **Actionable connection-error messages** (`src/util/provider-error.ts`) — `friendlyProviderError` now recognizes `ConnectionContextError` (names the provider + base URL; local providers get "start the server" guidance, others get "check the base URL / network" guidance) and bare `isConnectionError` failures as a defensive fallback, replacing the raw Bun message with `Could not connect to <provider> at <url>. …` in every case.
+- **Connection failures are now retryable** (`src/util/retry.ts`) — `defaultRetryable` treats `isConnectionError` as retryable (a local server mid-restart, or a transient DNS blip, can clear within the backoff budget); a persistently-down provider still exhausts the budget and surfaces the new actionable message rather than the raw one.
+
+### Added
+- **Reachability veto gate tests** (`test/launch-prompt-routing.test.ts`) — 5 tests covering the veto firing on an unreachable ollama pin, no false positive when reachable, `/route why` naming the fallback, `warnOnce` notice suppression across turns, and confirming cloud-provider routes never trigger the live probe.
+- **`isLocalProviderReachable` unit tests** (`test/model-discovery.test.ts`) — reachable/unreachable/non-ok-status coverage.
+- **`ConnectionContextError`/`withConnectionContext` unit tests** (`test/retry.test.ts`) — wrapping, pass-through of non-connection errors, and `defaultRetryable` classification.
+- **`friendlyProviderError` connection-message tests** (`test/provider-error-taxonomy.test.ts`) — local vs. non-local guidance, and the bare-error fallback.
+- **`model-manager` integration tests** (`test/model-provider-mapping.test.ts`) — `call()` and `stream()` both re-throw a raw connection failure as `ConnectionContextError` naming the correct provider/base URL.
+
+## [0.8.10] - 2026-07-08
+_"지피티 모델 연결이 안되는데 원인파악해서 개선해" — OpenAI's Codex/Responses backend (used by every `gpt-5.5`/`gpt-5.4` OAuth call, and by API-key reasoning models) can emit an in-band `response.failed`/`error` SSE EVENT on an otherwise-200 stream (documented codes: `server_error`, `rate_limit_exceeded` — OpenAI's own guidance is "retry with exponential backoff"). This was thrown as an unclassified bare `Error`, which propagated straight out of the engine's model call with NO retry — a transient OpenAI backend hiccup killed the whole turn outright, surfacing as "GPT doesn't connect" during real interactive use even though `jeo doctor` and a fresh one-shot call both looked healthy (the failure only manifests mid-stream, after the connection has already succeeded)._
+
+### Fixed
+- **In-band SSE error now retries instead of hard-failing** (`src/ai/providers/errors.ts`, `src/ai/providers/openai-responses.ts`, `src/util/retry.ts`, `src/agent/engine.ts`) — new `ProviderStreamError` class carries a synthetic `.status` (429 for `rate_limit_exceeded`, 500 otherwise) so existing retry classifiers treat it like the equivalent HTTP failure; `codexResponsesCall`/`codexResponsesStream` now throw it instead of a bare `Error`; the engine's mid-stream transient-network retry ladder (bounded, capped exponential backoff) now also catches it, sharing ONE retry budget with the existing socket-drop recovery path rather than two independent budgets.
+
+### Added
+- **In-band SSE error retry regression tests** (`test/codex-responses.test.ts`, `test/transient-network-recovery.test.ts`) — cover error-code capture on both SSE error shapes, `ProviderStreamError` retry classification, engine-level recovery from a mid-stream fault, and the shared retry-budget invariant across BOTH failure classes crossing the total cap (not just staying under a per-class cap).
+
 ## [0.8.9] - 2026-07-08
 _"프롬프트 라우팅 속도 문제가 있는거같은데 근본원인 알려줘" — prompt routing incurred significant latency due to a design oversight in LLM-based escalation: when heuristic confidence falls below threshold (standard conceptual questions with no code blocks/file paths conflict-trigger 0.35 confidence), it makes a blocking, synchronous LLM classifier call. If the user's global `thinkingLevel` is enabled (medium/high/xhigh), the cheap classifier model (Haiku 4.5 / GPT-4o-mini) also ran with reasoning enabled, wasting 500ms–1500ms on internal thoughts for a simple 1-word JSON response. The same reasoning-latency leak existed on all other background/internal LLM calls (compaction summarizer, goal verifier, memory distiller), blocking user turns on compaction boundaries._
 

package/README.ja.md

@@ -262,11 +262,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.11]** (2026-07-08) — "프롬프트 라우팅 동작이 Error: Unable to connect. Is the computer able to access the url? Error: Was there a typo in the url or port? 와 같은 메시지 남기고 동작안하는데 원인을 파악하고 근본문제해결하자" — traced the raw, provider-less connection error to two compounding gaps. (1) `describeProvider` reports local providers (ollama/lmstudio) as `ready: true` UNCONDITIONALLY — "keyless" only means no credential is required, never that the server is actually reachable — so the routing veto gate (which exists precisely to keep a misconfigured routing target from making a turn worse than routing being off) had no way to catch a `routing.tiers`/`roles` pin to a downed local server. (2) Bun's fetch/undici throws a bare `Error("Unable to connect. Is the computer able to access the url?")` with `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable host — no HTTP status, no provider name, no URL — and this fell through every existing error classifier (`defaultRetryable`, `friendlyProviderError`) to reach the user completely unfiltered.
+- **[0.8.10]** (2026-07-08) — "지피티 모델 연결이 안되는데 원인파악해서 개선해" — OpenAI's Codex/Responses backend (used by every `gpt-5.5`/`gpt-5.4` OAuth call, and by API-key reasoning models) can emit an in-band `response.failed`/`error` SSE EVENT on an otherwise-200 stream (documented codes: `server_error`, `rate_limit_exceeded` — OpenAI's own guidance is "retry with exponential backoff"). This was thrown as an unclassified bare `Error`, which propagated straight out of the engine's model call with NO retry — a transient OpenAI backend hiccup killed the whole turn outright, surfacing as "GPT doesn't connect" during real interactive use even though `jeo doctor` and a fresh one-shot call both looked healthy (the failure only manifests mid-stream, after the connection has already succeeded).
 - **[0.8.9]** (2026-07-08) — "프롬프트 라우팅 속도 문제가 있는거같은데 근본원인 알려줘" — prompt routing incurred significant latency due to a design oversight in LLM-based escalation: when heuristic confidence falls below threshold (standard conceptual questions with no code blocks/file paths conflict-trigger 0.35 confidence), it makes a blocking, synchronous LLM classifier call. If the user's global `thinkingLevel` is enabled (medium/high/xhigh), the cheap classifier model (Haiku 4.5 / GPT-4o-mini) also ran with reasoning enabled, wasting 500ms–1500ms on internal thoughts for a simple 1-word JSON response. The same reasoning-latency leak existed on all other background/internal LLM calls (compaction summarizer, goal verifier, memory distiller), blocking user turns on compaction boundaries.
 - **[0.8.8]** (2026-07-08) — "실동작검증을 통해서 유효성 평가하고 개선해줘" — live-verified the v0.8.5 fallback mechanism using active Claude Code OAuth credentials on this machine (confirmed 200 OK for both Fable 5 and Opus 4.8 via the proxy). Identified two critical improvement vectors during verification: (1) server-side fallback was previously scoped strictly to API-key credentials, leaving OAuth users (who also hit `reasoning_extraction` refusals) with today's reactive-only recovery; (2) the sequential `postAnthropic` retry ladder could throw immediately on a combination of different error types (e.g. temperature error first, then fallback error, then success).
 - **[0.8.7]** (2026-07-08) — Fix-forward for a CI-caught release failure in v0.8.6 (this same session): `test/launch-prompt-routing.test.ts` shipped with a dropped closing brace (a git 3-way merge misaligned on a duplicate `});` line during this session's own working-tree isolation, then a subsequent `git stash push --keep-index` silently reset the working tree to the pre-fix staged content — the fix was applied once, verified once, then invisibly reverted before the commit that actually shipped). The v0.8.6 GitHub Actions release workflow correctly caught the syntax error at `bun test` and failed BEFORE the npm publish step ran; `npm view jeo-code version` confirmed 0.8.5 remained latest throughout — nothing broken ever reached the registry. Per this repo's established pattern for a same-day CI-caught regression (v0.8.0 → v0.8.1), shipping forward rather than retargeting the already-publicly-failed v0.8.6 tag.
-- **[0.8.6]** (2026-07-08) — Explicit `/model` pin always winning over PromptRouter was correct but opaque: `/route status` showed "routing: on" even while a session pin blocked routing from ever evaluating a prompt, and there was no way back to routed mode short of restarting the session. Also closed a related escalation gap: `routing.enabled` with `roles.smol` unset made ambiguous-prompt LLM escalation silently skip every turn, even when a cheaper credentialed model existed to run the classifier.
-- **[0.8.5]** (2026-07-08) — "딥리서치 다음과같이 페이블5 모델이 응답하게 되는경우를 피하기 위해" — a claude-fable-5 turn hit `Error: Refusal (reasoning_extraction): This request was blocked as it seems to violate Anthropic's Terms of Service.` jeo already had a full reactive recovery ladder (context reset → thinking-artifact strip → guidance strip → fail-fast on a category-shaped refusal), but every rung still resends to the SAME model — a deterministic classifier trip re-refuses identically no matter how much context gets stripped. Deep-researched Anthropic's current docs and found the actual fix: a documented, dedicated **server-side fallback** beta released alongside Fable 5 that retries a safety-classifier decline against a different model inside the SAME request, before the caller ever sees an error.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -263,11 +263,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.11]** (2026-07-08) — "프롬프트 라우팅 동작이 Error: Unable to connect. Is the computer able to access the url? Error: Was there a typo in the url or port? 와 같은 메시지 남기고 동작안하는데 원인을 파악하고 근본문제해결하자" — traced the raw, provider-less connection error to two compounding gaps. (1) `describeProvider` reports local providers (ollama/lmstudio) as `ready: true` UNCONDITIONALLY — "keyless" only means no credential is required, never that the server is actually reachable — so the routing veto gate (which exists precisely to keep a misconfigured routing target from making a turn worse than routing being off) had no way to catch a `routing.tiers`/`roles` pin to a downed local server. (2) Bun's fetch/undici throws a bare `Error("Unable to connect. Is the computer able to access the url?")` with `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable host — no HTTP status, no provider name, no URL — and this fell through every existing error classifier (`defaultRetryable`, `friendlyProviderError`) to reach the user completely unfiltered.
+- **[0.8.10]** (2026-07-08) — "지피티 모델 연결이 안되는데 원인파악해서 개선해" — OpenAI's Codex/Responses backend (used by every `gpt-5.5`/`gpt-5.4` OAuth call, and by API-key reasoning models) can emit an in-band `response.failed`/`error` SSE EVENT on an otherwise-200 stream (documented codes: `server_error`, `rate_limit_exceeded` — OpenAI's own guidance is "retry with exponential backoff"). This was thrown as an unclassified bare `Error`, which propagated straight out of the engine's model call with NO retry — a transient OpenAI backend hiccup killed the whole turn outright, surfacing as "GPT doesn't connect" during real interactive use even though `jeo doctor` and a fresh one-shot call both looked healthy (the failure only manifests mid-stream, after the connection has already succeeded).
 - **[0.8.9]** (2026-07-08) — "프롬프트 라우팅 속도 문제가 있는거같은데 근본원인 알려줘" — prompt routing incurred significant latency due to a design oversight in LLM-based escalation: when heuristic confidence falls below threshold (standard conceptual questions with no code blocks/file paths conflict-trigger 0.35 confidence), it makes a blocking, synchronous LLM classifier call. If the user's global `thinkingLevel` is enabled (medium/high/xhigh), the cheap classifier model (Haiku 4.5 / GPT-4o-mini) also ran with reasoning enabled, wasting 500ms–1500ms on internal thoughts for a simple 1-word JSON response. The same reasoning-latency leak existed on all other background/internal LLM calls (compaction summarizer, goal verifier, memory distiller), blocking user turns on compaction boundaries.
 - **[0.8.8]** (2026-07-08) — "실동작검증을 통해서 유효성 평가하고 개선해줘" — live-verified the v0.8.5 fallback mechanism using active Claude Code OAuth credentials on this machine (confirmed 200 OK for both Fable 5 and Opus 4.8 via the proxy). Identified two critical improvement vectors during verification: (1) server-side fallback was previously scoped strictly to API-key credentials, leaving OAuth users (who also hit `reasoning_extraction` refusals) with today's reactive-only recovery; (2) the sequential `postAnthropic` retry ladder could throw immediately on a combination of different error types (e.g. temperature error first, then fallback error, then success).
 - **[0.8.7]** (2026-07-08) — Fix-forward for a CI-caught release failure in v0.8.6 (this same session): `test/launch-prompt-routing.test.ts` shipped with a dropped closing brace (a git 3-way merge misaligned on a duplicate `});` line during this session's own working-tree isolation, then a subsequent `git stash push --keep-index` silently reset the working tree to the pre-fix staged content — the fix was applied once, verified once, then invisibly reverted before the commit that actually shipped). The v0.8.6 GitHub Actions release workflow correctly caught the syntax error at `bun test` and failed BEFORE the npm publish step ran; `npm view jeo-code version` confirmed 0.8.5 remained latest throughout — nothing broken ever reached the registry. Per this repo's established pattern for a same-day CI-caught regression (v0.8.0 → v0.8.1), shipping forward rather than retargeting the already-publicly-failed v0.8.6 tag.
-- **[0.8.6]** (2026-07-08) — Explicit `/model` pin always winning over PromptRouter was correct but opaque: `/route status` showed "routing: on" even while a session pin blocked routing from ever evaluating a prompt, and there was no way back to routed mode short of restarting the session. Also closed a related escalation gap: `routing.enabled` with `roles.smol` unset made ambiguous-prompt LLM escalation silently skip every turn, even when a cheaper credentialed model existed to run the classifier.
-- **[0.8.5]** (2026-07-08) — "딥리서치 다음과같이 페이블5 모델이 응답하게 되는경우를 피하기 위해" — a claude-fable-5 turn hit `Error: Refusal (reasoning_extraction): This request was blocked as it seems to violate Anthropic's Terms of Service.` jeo already had a full reactive recovery ladder (context reset → thinking-artifact strip → guidance strip → fail-fast on a category-shaped refusal), but every rung still resends to the SAME model — a deterministic classifier trip re-refuses identically no matter how much context gets stripped. Deep-researched Anthropic's current docs and found the actual fix: a documented, dedicated **server-side fallback** beta released alongside Fable 5 that retries a safety-classifier decline against a different model inside the SAME request, before the caller ever sees an error.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -265,11 +265,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.11]** (2026-07-08) — "프롬프트 라우팅 동작이 Error: Unable to connect. Is the computer able to access the url? Error: Was there a typo in the url or port? 와 같은 메시지 남기고 동작안하는데 원인을 파악하고 근본문제해결하자" — traced the raw, provider-less connection error to two compounding gaps. (1) `describeProvider` reports local providers (ollama/lmstudio) as `ready: true` UNCONDITIONALLY — "keyless" only means no credential is required, never that the server is actually reachable — so the routing veto gate (which exists precisely to keep a misconfigured routing target from making a turn worse than routing being off) had no way to catch a `routing.tiers`/`roles` pin to a downed local server. (2) Bun's fetch/undici throws a bare `Error("Unable to connect. Is the computer able to access the url?")` with `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable host — no HTTP status, no provider name, no URL — and this fell through every existing error classifier (`defaultRetryable`, `friendlyProviderError`) to reach the user completely unfiltered.
+- **[0.8.10]** (2026-07-08) — "지피티 모델 연결이 안되는데 원인파악해서 개선해" — OpenAI's Codex/Responses backend (used by every `gpt-5.5`/`gpt-5.4` OAuth call, and by API-key reasoning models) can emit an in-band `response.failed`/`error` SSE EVENT on an otherwise-200 stream (documented codes: `server_error`, `rate_limit_exceeded` — OpenAI's own guidance is "retry with exponential backoff"). This was thrown as an unclassified bare `Error`, which propagated straight out of the engine's model call with NO retry — a transient OpenAI backend hiccup killed the whole turn outright, surfacing as "GPT doesn't connect" during real interactive use even though `jeo doctor` and a fresh one-shot call both looked healthy (the failure only manifests mid-stream, after the connection has already succeeded).
 - **[0.8.9]** (2026-07-08) — "프롬프트 라우팅 속도 문제가 있는거같은데 근본원인 알려줘" — prompt routing incurred significant latency due to a design oversight in LLM-based escalation: when heuristic confidence falls below threshold (standard conceptual questions with no code blocks/file paths conflict-trigger 0.35 confidence), it makes a blocking, synchronous LLM classifier call. If the user's global `thinkingLevel` is enabled (medium/high/xhigh), the cheap classifier model (Haiku 4.5 / GPT-4o-mini) also ran with reasoning enabled, wasting 500ms–1500ms on internal thoughts for a simple 1-word JSON response. The same reasoning-latency leak existed on all other background/internal LLM calls (compaction summarizer, goal verifier, memory distiller), blocking user turns on compaction boundaries.
 - **[0.8.8]** (2026-07-08) — "실동작검증을 통해서 유효성 평가하고 개선해줘" — live-verified the v0.8.5 fallback mechanism using active Claude Code OAuth credentials on this machine (confirmed 200 OK for both Fable 5 and Opus 4.8 via the proxy). Identified two critical improvement vectors during verification: (1) server-side fallback was previously scoped strictly to API-key credentials, leaving OAuth users (who also hit `reasoning_extraction` refusals) with today's reactive-only recovery; (2) the sequential `postAnthropic` retry ladder could throw immediately on a combination of different error types (e.g. temperature error first, then fallback error, then success).
 - **[0.8.7]** (2026-07-08) — Fix-forward for a CI-caught release failure in v0.8.6 (this same session): `test/launch-prompt-routing.test.ts` shipped with a dropped closing brace (a git 3-way merge misaligned on a duplicate `});` line during this session's own working-tree isolation, then a subsequent `git stash push --keep-index` silently reset the working tree to the pre-fix staged content — the fix was applied once, verified once, then invisibly reverted before the commit that actually shipped). The v0.8.6 GitHub Actions release workflow correctly caught the syntax error at `bun test` and failed BEFORE the npm publish step ran; `npm view jeo-code version` confirmed 0.8.5 remained latest throughout — nothing broken ever reached the registry. Per this repo's established pattern for a same-day CI-caught regression (v0.8.0 → v0.8.1), shipping forward rather than retargeting the already-publicly-failed v0.8.6 tag.
-- **[0.8.6]** (2026-07-08) — Explicit `/model` pin always winning over PromptRouter was correct but opaque: `/route status` showed "routing: on" even while a session pin blocked routing from ever evaluating a prompt, and there was no way back to routed mode short of restarting the session. Also closed a related escalation gap: `routing.enabled` with `roles.smol` unset made ambiguous-prompt LLM escalation silently skip every turn, even when a cheaper credentialed model existed to run the classifier.
-- **[0.8.5]** (2026-07-08) — "딥리서치 다음과같이 페이블5 모델이 응답하게 되는경우를 피하기 위해" — a claude-fable-5 turn hit `Error: Refusal (reasoning_extraction): This request was blocked as it seems to violate Anthropic's Terms of Service.` jeo already had a full reactive recovery ladder (context reset → thinking-artifact strip → guidance strip → fail-fast on a category-shaped refusal), but every rung still resends to the SAME model — a deterministic classifier trip re-refuses identically no matter how much context gets stripped. Deep-researched Anthropic's current docs and found the actual fix: a documented, dedicated **server-side fallback** beta released alongside Fable 5 that retries a safety-classifier decline against a different model inside the SAME request, before the caller ever sees an error.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -262,11 +262,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.11]** (2026-07-08) — "프롬프트 라우팅 동작이 Error: Unable to connect. Is the computer able to access the url? Error: Was there a typo in the url or port? 와 같은 메시지 남기고 동작안하는데 원인을 파악하고 근본문제해결하자" — traced the raw, provider-less connection error to two compounding gaps. (1) `describeProvider` reports local providers (ollama/lmstudio) as `ready: true` UNCONDITIONALLY — "keyless" only means no credential is required, never that the server is actually reachable — so the routing veto gate (which exists precisely to keep a misconfigured routing target from making a turn worse than routing being off) had no way to catch a `routing.tiers`/`roles` pin to a downed local server. (2) Bun's fetch/undici throws a bare `Error("Unable to connect. Is the computer able to access the url?")` with `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable host — no HTTP status, no provider name, no URL — and this fell through every existing error classifier (`defaultRetryable`, `friendlyProviderError`) to reach the user completely unfiltered.
+- **[0.8.10]** (2026-07-08) — "지피티 모델 연결이 안되는데 원인파악해서 개선해" — OpenAI's Codex/Responses backend (used by every `gpt-5.5`/`gpt-5.4` OAuth call, and by API-key reasoning models) can emit an in-band `response.failed`/`error` SSE EVENT on an otherwise-200 stream (documented codes: `server_error`, `rate_limit_exceeded` — OpenAI's own guidance is "retry with exponential backoff"). This was thrown as an unclassified bare `Error`, which propagated straight out of the engine's model call with NO retry — a transient OpenAI backend hiccup killed the whole turn outright, surfacing as "GPT doesn't connect" during real interactive use even though `jeo doctor` and a fresh one-shot call both looked healthy (the failure only manifests mid-stream, after the connection has already succeeded).
 - **[0.8.9]** (2026-07-08) — "프롬프트 라우팅 속도 문제가 있는거같은데 근본원인 알려줘" — prompt routing incurred significant latency due to a design oversight in LLM-based escalation: when heuristic confidence falls below threshold (standard conceptual questions with no code blocks/file paths conflict-trigger 0.35 confidence), it makes a blocking, synchronous LLM classifier call. If the user's global `thinkingLevel` is enabled (medium/high/xhigh), the cheap classifier model (Haiku 4.5 / GPT-4o-mini) also ran with reasoning enabled, wasting 500ms–1500ms on internal thoughts for a simple 1-word JSON response. The same reasoning-latency leak existed on all other background/internal LLM calls (compaction summarizer, goal verifier, memory distiller), blocking user turns on compaction boundaries.
 - **[0.8.8]** (2026-07-08) — "실동작검증을 통해서 유효성 평가하고 개선해줘" — live-verified the v0.8.5 fallback mechanism using active Claude Code OAuth credentials on this machine (confirmed 200 OK for both Fable 5 and Opus 4.8 via the proxy). Identified two critical improvement vectors during verification: (1) server-side fallback was previously scoped strictly to API-key credentials, leaving OAuth users (who also hit `reasoning_extraction` refusals) with today's reactive-only recovery; (2) the sequential `postAnthropic` retry ladder could throw immediately on a combination of different error types (e.g. temperature error first, then fallback error, then success).
 - **[0.8.7]** (2026-07-08) — Fix-forward for a CI-caught release failure in v0.8.6 (this same session): `test/launch-prompt-routing.test.ts` shipped with a dropped closing brace (a git 3-way merge misaligned on a duplicate `});` line during this session's own working-tree isolation, then a subsequent `git stash push --keep-index` silently reset the working tree to the pre-fix staged content — the fix was applied once, verified once, then invisibly reverted before the commit that actually shipped). The v0.8.6 GitHub Actions release workflow correctly caught the syntax error at `bun test` and failed BEFORE the npm publish step ran; `npm view jeo-code version` confirmed 0.8.5 remained latest throughout — nothing broken ever reached the registry. Per this repo's established pattern for a same-day CI-caught regression (v0.8.0 → v0.8.1), shipping forward rather than retargeting the already-publicly-failed v0.8.6 tag.
-- **[0.8.6]** (2026-07-08) — Explicit `/model` pin always winning over PromptRouter was correct but opaque: `/route status` showed "routing: on" even while a session pin blocked routing from ever evaluating a prompt, and there was no way back to routed mode short of restarting the session. Also closed a related escalation gap: `routing.enabled` with `roles.smol` unset made ambiguous-prompt LLM escalation silently skip every turn, even when a cheaper credentialed model existed to run the classifier.
-- **[0.8.5]** (2026-07-08) — "딥리서치 다음과같이 페이블5 모델이 응답하게 되는경우를 피하기 위해" — a claude-fable-5 turn hit `Error: Refusal (reasoning_extraction): This request was blocked as it seems to violate Anthropic's Terms of Service.` jeo already had a full reactive recovery ladder (context reset → thinking-artifact strip → guidance strip → fail-fast on a category-shaped refusal), but every rung still resends to the SAME model — a deterministic classifier trip re-refuses identically no matter how much context gets stripped. Deep-researched Anthropic's current docs and found the actual fix: a documented, dedicated **server-side fallback** beta released alongside Fable 5 that retries a safety-classifier decline against a different model inside the SAME request, before the caller ever sees an error.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/engine.ts

@@ -22,7 +22,7 @@ import { createLspTool } from "./lsp-tool";
 import { createLspRenameTool } from "./lsp-rename-tool";
 import { createDebugTool } from "./debug-tool";
 import { createBrowserTool } from "./browser-tool";
-import { isRateLimitError, isTransientStreamDropError, waitAbortable } from "../util/retry";
+import { isRateLimitError, isTransientStreamDropError, isProviderStreamError, waitAbortable } from "../util/retry";
 import { isContextOverflowError, isRefusalError, friendlyProviderError } from "../util/provider-error";
 import { runPreToolHooks, runPostTurnHooksForBatch } from "./hooks";
 import { truncateToolOutput, formatToolResultBody } from "./tool-output";
@@ -818,14 +818,22 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         await waitAbortable(delayMs, opts.signal);
         continue; // loop top surfaces "Cancelled." when the wait was aborted
       }
-      // Mid-stream transient-network drop (see `transientNetworkRetries` above): bounded
-      // resend with capped exponential backoff. Deliberately narrower than a general
-      // `defaultRetryable` check — a rate-limit/5xx/timeout error already ran the FULL
-      // model-manager `withRetry` budget (visible as its own "auto-retry #N" notices)
-      // before reaching here, so re-retrying it in this ladder too would silently double
-      // that budget. `isTransientStreamDropError` matches only the mid-stream socket-death
-      // class that `retryableStream` structurally cannot retry once a chunk has streamed.
-      if (isTransientStreamDropError(err)) {
+      // Mid-stream transient fault (see `transientNetworkRetries` above): bounded resend
+      // with capped exponential backoff, covering TWO distinct failure classes that both
+      // land here unretried:
+      //   - `isTransientStreamDropError` — a live TCP/TLS socket dying mid-stream.
+      //   - `isProviderStreamError` — an in-band SSE error EVENT on an otherwise-200
+      //     connection (OpenAI Responses `response.failed`/`error`, e.g. `server_error`).
+      // Deliberately narrower than a general `defaultRetryable` check — a rate-limit/5xx/
+      // timeout error already ran the FULL model-manager `withRetry` budget (visible as
+      // its own "auto-retry #N" notices) before reaching here, so re-retrying it in this
+      // ladder too would silently double that budget. Both classes above are structurally
+      // exempt from that budget: `retryableStream` (model-manager.ts) only auto-retries
+      // losing the FIRST chunk — once any chunk has streamed it deliberately stops (a full
+      // re-call would replay already-emitted content) — so a fault arriving AFTER the
+      // first chunk never got a model-manager retry at all and needs this engine-level
+      // recovery instead.
+      if (isTransientStreamDropError(err) || isProviderStreamError(err)) {
         transientNetworkRetries++;
         if (transientNetworkRetries <= GUARD_LIMITS.MAX_TRANSIENT_NETWORK_RETRIES) {
           const baseRaw = Number(jeoEnv("TRANSIENT_NETWORK_BACKOFF_BASE_MS") ?? NaN);
@@ -833,7 +841,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           const delayMs = Math.min(baseMs * 2 ** (transientNetworkRetries - 1), GUARD_LIMITS.TRANSIENT_NETWORK_BACKOFF_MAX_MS);
           const escHint = ev.onModelStream ? " (Esc to cancel)" : "";
           ev.onNotice?.(
-            `connection dropped mid-response (${friendlyProviderError(err)}) — auto-retry #${transientNetworkRetries} in ${Math.max(1, Math.round(delayMs / 1000))}s${escHint}`,
+            `mid-response provider fault (${friendlyProviderError(err)}) — auto-retry #${transientNetworkRetries} in ${Math.max(1, Math.round(delayMs / 1000))}s${escHint}`,
           );
           await waitAbortable(delayMs, opts.signal);
           continue; // loop top surfaces "Cancelled." when the wait was aborted

package/src/ai/model-discovery.ts

@@ -412,6 +412,27 @@ export async function listProviderModels(
   }
 }
 
+/** Live reachability probe for a KEYLESS local provider (ollama/lmstudio) — the
+ *  narrow gap `describeProvider` leaves open: it reports these as `ready: true`
+ *  unconditionally (keyless means "no credential needed", not "server is up"), so
+ *  a routing decision that lands on a downed local server previously sailed past
+ *  every readiness check and only failed at call time with a raw, unhelpful
+ *  connection error (see `friendlyProviderError`'s `ConnectionContextError`
+ *  branch for the same failure surfaced OUTSIDE this proactive check, e.g. an
+ *  explicit `/model ollama/...` pin). Reuses `listProviderModels`'s tested
+ *  fetch/timeout/error handling — never throws. `timeoutMs` defaults short
+ *  (1500ms, well under `listProviderModels`'s 5000ms default): a live loopback
+ *  service answers in single-digit ms, so this stays cheap on the turn hot path
+ *  and still fails fast on a genuinely unreachable host. */
+export async function isLocalProviderReachable(
+  provider: "ollama" | "lmstudio",
+  baseUrl: string | undefined,
+  opts: Pick<DiscoveryOptions, "timeoutMs" | "fetchImpl"> = {},
+): Promise<boolean> {
+  const result = await listProviderModels(provider, { baseUrl, timeoutMs: opts.timeoutMs ?? 1500, fetchImpl: opts.fetchImpl, limit: 1 });
+  return result.ok;
+}
+
 /**
  * Discover live models across providers. By default only queries providers that
  * are logged in / reachable (skips `none` cloud providers); ollama is always

package/src/ai/model-manager.ts

@@ -9,7 +9,7 @@ import { findCatalogEntry, type ModelCatalogEntry } from "./model-catalog-compat
 import { toProviderModel, CODEX_MODELS, KIMI_CODE_MODELS, findCatalogModel } from "./model-catalog";
 import { xaiCredential } from "./providers/xai";
 import { OPENAI_COMPAT_NAMES, isOpenAICompatProvider } from "./providers/openai-compatible-catalog";
-import { withRetry, defaultRetryable, type RetryOptions } from "../util/retry";
+import { withRetry, defaultRetryable, withConnectionContext, isConnectionError, ConnectionContextError, type RetryOptions } from "../util/retry";
 import { jeoEnv } from "../util/env";
 import type { Config } from "../agent/state";
 
@@ -380,6 +380,12 @@ interface Resolved {
   callOptions: CallOptions;
   credential: Credential;
   retry: RetryOptions;
+  /** The resolved provider + effective base URL, threaded through so a raw
+   *  pre-response connection failure (see `isConnectionError`) can be enriched
+   *  with "which provider/URL was unreachable" before it reaches the user —
+   *  the bare fetch error carries neither. */
+  provider: ProviderName;
+  baseUrl: string | undefined;
 }
 
 /**
@@ -452,13 +458,13 @@ export async function resolveCall(options: Partial<CallOptions>, kind: "request"
   const retry: RetryOptions = { ...resolveRetryOptions(config.retry, kind), ...(options.onRetry ? { onRetry: options.onRetry } : {}), ...(callOptions.signal ? { signal: callOptions.signal } : {}) };
 
   if (provider === "ollama" || provider === "lmstudio") {
-    return { adapter, callOptions, credential: { kind: "none", provider: "openai" }, retry };
+    return { adapter, callOptions, credential: { kind: "none", provider: "openai" }, retry, provider, baseUrl };
   }
 
   if (provider === "xai") {
     const key = config.providers?.xai;
     if (!key) throw new Error("No credential for provider 'xai'. Set XAI_API_KEY (or providers.xai in config).");
-    return { adapter, callOptions, credential: xaiCredential(key), retry };
+    return { adapter, callOptions, credential: xaiCredential(key), retry, provider, baseUrl };
   }
 
   if (provider === "antigravity") {
@@ -472,7 +478,7 @@ export async function resolveCall(options: Partial<CallOptions>, kind: "request"
     if (credential.kind !== "oauth") {
       throw new Error("Antigravity models use Google OAuth. Run 'jeo auth login antigravity' (recommended) or 'jeo auth login gemini', then retry — the Google Cloud projectId is discovered automatically.");
     }
-    return { adapter, callOptions, credential, retry };
+    return { adapter, callOptions, credential, retry, provider, baseUrl };
   }
 
   const credentialProvider = provider as AuthProvider;
@@ -494,7 +500,7 @@ export async function resolveCall(options: Partial<CallOptions>, kind: "request"
       `No credential for provider '${provider}'. Run 'jeo setup', 'jeo auth login', or set ${provider.toUpperCase()}_API_KEY / ${provider.toUpperCase()}_OAUTH_TOKEN.`
     );
   }
-  return { adapter, callOptions, credential: credentialForCall(provider, effective, config, baseUrl), retry };
+  return { adapter, callOptions, credential: credentialForCall(provider, effective, config, baseUrl), retry, provider, baseUrl };
 }
 
 /** Hard wall-clock cap for a single NON-streaming provider request (service-readiness: a
@@ -694,11 +700,15 @@ export function createModelManager(): ModelManager {
   return {
     resolveProvider,
     async call(messages, options = {}) {
-      const { adapter, callOptions, credential, retry } = await resolveCall(options);
-      return withRetry(() => adapter.call(messages, { ...callOptions, signal: withTimeout(callOptions.signal, callTimeoutMs()) }, credential), retry);
+      const { adapter, callOptions, credential, retry, provider, baseUrl } = await resolveCall(options);
+      return withConnectionContext(
+        () => withRetry(() => adapter.call(messages, { ...callOptions, signal: withTimeout(callOptions.signal, callTimeoutMs()) }, credential), retry),
+        provider,
+        baseUrl,
+      );
     },
     async *stream(messages, options = {}) {
-      const { adapter, callOptions, credential, retry } = await resolveCall(options, "stream");
+      const { adapter, callOptions, credential, retry, provider, baseUrl } = await resolveCall(options, "stream");
       if (adapter.stream) {
         const streamFn = adapter.stream.bind(adapter);
         // Per-attempt abort controller fired by the idle timeout — so a stalled stream
@@ -733,15 +743,24 @@ export function createModelManager(): ModelManager {
           return streamFn(messages, { ...liveOptions, signal }, credential)[Symbol.asyncIterator]();
         };
         const maxMs = streamMaxMs();
-        yield* retryableStream(makeIter, retry, {
-          idleMs: streamIdleMs(),
-          ...(maxMs !== undefined ? { deadlineAt: Date.now() + maxMs } : {}),
-          lastActivityAt: () => lastActivityAt,
-          onIdle: () => attempt?.abort(),
-        });
+        try {
+          yield* retryableStream(makeIter, retry, {
+            idleMs: streamIdleMs(),
+            ...(maxMs !== undefined ? { deadlineAt: Date.now() + maxMs } : {}),
+            lastActivityAt: () => lastActivityAt,
+            onIdle: () => attempt?.abort(),
+          });
+        } catch (err) {
+          if (isConnectionError(err)) throw new ConnectionContextError(provider, baseUrl, err);
+          throw err;
+        }
       } else {
         // Fallback: providers without streaming yield the full response as one chunk.
-        yield await withRetry(() => adapter.call(messages, { ...callOptions, signal: withTimeout(callOptions.signal, callTimeoutMs()) }, credential), retry);
+        yield await withConnectionContext(
+          () => withRetry(() => adapter.call(messages, { ...callOptions, signal: withTimeout(callOptions.signal, callTimeoutMs()) }, credential), retry),
+          provider,
+          baseUrl,
+        );
       }
     },
   };

package/src/ai/providers/errors.ts

@@ -21,6 +21,33 @@ export class ProviderHttpError extends Error {
   }
 }
 
+/**
+ * In-band stream failure: the HTTP response itself was 200 (a live SSE
+ * connection), but the provider emitted a terminal error EVENT instead of
+ * completing normally (OpenAI Responses `response.failed`/`error`: `{"error":
+ * {"code":"server_error","message":"…"}}`). No `Response` object survives to
+ * build a `ProviderHttpError` from, so this carries a SYNTHETIC `.status` —
+ * 429 for a rate-limit code, 500 otherwise — purely so the existing
+ * status-based retry checks (`defaultRetryable`, `isRateLimitError`) treat it
+ * exactly like the equivalent HTTP failure instead of falling through as an
+ * unclassified bare Error (OpenAI's own guidance for `server_error`/
+ * `rate_limit_exceeded` is "retry with exponential backoff" — every other
+ * code is unenumerated/rare enough that defaulting to retryable is safer than
+ * hard-failing a whole turn on a transient backend hiccup).
+ */
+export class ProviderStreamError extends Error {
+  readonly status: number;
+  readonly provider: string;
+  readonly code?: string;
+  constructor(provider: string, message: string, code?: string) {
+    super(`${provider} stream failed${code ? ` (${code})` : ""}: ${message}`);
+    this.name = "ProviderStreamError";
+    this.status = code === "rate_limit_exceeded" ? 429 : 500;
+    this.provider = provider;
+    this.code = code;
+  }
+}
+
 /**
  * Parse a `Retry-After` header into ms. Supports the delta-seconds form
  * (`"5"`) and the HTTP-date form (`"Wed, 21 Oct 2025 07:28:00 GMT"`).

package/src/ai/providers/openai-responses.ts

@@ -13,7 +13,7 @@
 import type { Credential } from "../../auth";
 import type { CallOptions, Message } from "../types";
 import { readSse } from "../sse";
-import { providerHttpError, fetchWithArtifactFailSafe } from "./errors";
+import { providerHttpError, fetchWithArtifactFailSafe, ProviderStreamError } from "./errors";
 import { serializeAccumulatedToolCalls } from "../../agent/tool-schemas";
 import { sanitizeJsonStrings } from "../../util/sanitize-json";
 import os from "node:os";
@@ -181,6 +181,10 @@ export interface ResponsesEvent {
   reasoningDelta?: string;
   usage?: { inputTokens?: number; outputTokens?: number };
   error?: string;
+  /** OpenAI's structured error `code` (e.g. `server_error`, `rate_limit_exceeded`) —
+   *  carried separately from the human-readable message so callers can classify
+   *  retryability without parsing prose (round: in-band SSE error retry fix). */
+  errorCode?: string;
   /** `response.incomplete` cause (e.g. max_output_tokens) — surfaced when the
    *  whole response produced no text (round-5 #1). */
   incompleteReason?: string;
@@ -201,10 +205,10 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
     output_index?: number;
     response?: {
       usage?: { input_tokens?: number; output_tokens?: number };
-      error?: { message?: string };
+      error?: { message?: string; code?: string };
       incomplete_details?: { reason?: string };
     };
-    error?: { message?: string };
+    error?: { message?: string; code?: string };
   };
   try {
     o = JSON.parse(data);
@@ -237,7 +241,8 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
     };
   }
   if (o.type === "response.failed" || o.type === "error") {
-    return { error: o.response?.error?.message ?? o.error?.message ?? "Codex response failed" };
+    const e = o.response?.error ?? o.error;
+    return { error: e?.message ?? "Codex response failed", errorCode: e?.code };
   }
   return {};
 }
@@ -294,7 +299,7 @@ export async function codexResponsesCall(messages: Message[], options: CallOptio
     accumulateResponsesToolCall(toolAcc, ev);
     if (ev.usage) options.onUsage?.(ev.usage);
     if (ev.incompleteReason) incompleteReason = ev.incompleteReason;
-    if (ev.error) throw new Error(`OpenAI Codex response failed: ${ev.error}`);
+    if (ev.error) throw new ProviderStreamError("OpenAI Codex", ev.error, ev.errorCode);
   }
   // Prefer a native tool call (re-serialized to canonical JSON) over any stray text.
   const envelope = serializeAccumulatedToolCalls(toolAcc);
@@ -326,7 +331,7 @@ export async function* codexResponsesStream(
     accumulateResponsesToolCall(toolAcc, ev);
     if (ev.usage) options.onUsage?.(ev.usage);
     if (ev.incompleteReason) incompleteReason = ev.incompleteReason;
-    if (ev.error) throw new Error(`OpenAI Codex response failed: ${ev.error}`);
+    if (ev.error) throw new ProviderStreamError("OpenAI Codex", ev.error, ev.errorCode);
   }
   // Native tool calls have no output_text deltas — yield the re-serialized envelope once.
   const envelope = serializeAccumulatedToolCalls(toolAcc);

package/src/commands/launch.ts

@@ -45,7 +45,7 @@ import { callLlm, type Message } from "../agent/loop";
 import { friendlyProviderError } from "../util/provider-error";
 import { readGlobalConfig, saveConfigPatch, resolveWikiRoot } from "../agent/state";
 import { rememberModelPatch, recentModelsForDisplay } from "../agent/model-recency";
-import { describeModel, describeAllProviders, describeProvider, resolveProvider, thinkingMaxTokens, resolveMaxOutputTokens, thinkingToReasoningEffort, discoverModels, flattenModels, resolveSelection, catalogMetadata, catalogByProvider, resolveRoleModel, CODEX_MODELS, qualifyModelId, modelServableWithConfig } from "../ai";
+import { describeModel, describeAllProviders, describeProvider, resolveProvider, thinkingMaxTokens, resolveMaxOutputTokens, thinkingToReasoningEffort, discoverModels, flattenModels, resolveSelection, catalogMetadata, catalogByProvider, resolveRoleModel, CODEX_MODELS, qualifyModelId, modelServableWithConfig, isLocalProviderReachable } from "../ai";
 import type { ProviderModelsResult, PickEntry, ProviderName, ModelRole, ThinkLevel } from "../ai";
 import { readGoalState, writeGoalState, clearGoalState, verifyGoal } from "../agent/goal-verifier";
 import { routePrompt, deriveCacheSessionKey, warnOnce, type RouteDecision } from "../agent/prompt-router";
@@ -926,6 +926,32 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           `[route] routed to '${routed.model}' but the stored ${routedProvider} OAuth login cannot serve that model — falling back to the default model this turn. Set ${routedProvider.toUpperCase()}_API_KEY or reconfigure routing.tiers/roles to a model your login serves.`,
         );
         routed = null;
+      } else if (routedProvider === "ollama" || routedProvider === "lmstudio") {
+        // Live reachability gate for LOCAL providers only: `describeProvider` reports
+        // ollama/lmstudio as `ready: true` unconditionally (keyless just means "no
+        // credential needed", not "the server is actually up"), so a routing.tiers/
+        // roles pin to a downed local server previously sailed past every readiness
+        // check above and only failed mid-turn with a raw, provider-less connection
+        // error ("Unable to connect. Is the computer able to access the url?" —
+        // Bun's fetch/undici error for a refused connection AND an unresolvable
+        // host alike). A short-timeout live probe here keeps routing's fail-open
+        // contract intact for the one credential class it couldn't previously see
+        // through. Cloud providers never reach this branch — their credential/
+        // servability checks above are sufficient and adding a live probe there
+        // would just add latency for a class of failure `withRetry` already
+        // recovers from at call time.
+        const localBaseUrl = routedProvider === "ollama"
+          ? (turnConfig.ollamaBaseUrl ?? "http://localhost:11434")
+          : (turnConfig.lmstudioBaseUrl ?? "http://localhost:1234/v1");
+        const reachable = await isLocalProviderReachable(routedProvider, localBaseUrl);
+        if (!reachable) {
+          routeVetoNote = `routed model '${routed.model}' (${routedProvider}) is unreachable at ${localBaseUrl} this turn — fell back to '${sessionModel || defaultModel}'`;
+          routeCredentialNotice = warnOnce(
+            `prompt-router:provider-unreachable:${routedProvider}`,
+            `[route] routed to '${routed.model}' (${routedProvider}) but ${localBaseUrl} is unreachable — falling back to the default model this turn. Start the ${routedProvider} server, or reconfigure routing.tiers/roles for a provider that is running.`,
+          );
+          routed = null;
+        }
       }
     }
     lastRouteDecision = routed ?? (routeVetoNote ? { note: routeVetoNote } : routingEnabled && !sessionModel ? { note: "routing produced no decision (fail-open)" } : { note: "routing not active this turn" });

package/src/util/provider-error.ts

@@ -4,7 +4,8 @@
  * (carrying `.status` and a body), and the agent loop surfaces failures both as a
  * thrown error and as a `doneReason`, so this lives in a shared util used by both.
  */
-import { isUsageLimitError, isRefusalError } from "./retry";
+import { isUsageLimitError, isRefusalError, isConnectionError, ConnectionContextError } from "./retry";
+import { companyLabel } from "../ai/model-catalog";
 // Re-export: engine.ts and callers import the refusal predicate from here; the
 // definition lives in retry.ts so defaultRetryable can fail fast without a cycle.
 export { isRefusalError } from "./retry";
@@ -32,6 +33,18 @@ function formatDuration(ms: number): string {
 }
 
 export function friendlyProviderError(err: unknown): string {
+  if (err instanceof ConnectionContextError) {
+    const provider = companyLabel(err.provider);
+    const target = err.baseUrl ? ` at ${err.baseUrl}` : "";
+    const isLocal = err.provider === "ollama" || err.provider === "lmstudio";
+    const hint = isLocal
+      ? ` Start the ${provider} server (or check it's still running), verify the base URL in 'jeo setup' / config.json ('${err.provider}BaseUrl'), or switch model with /model.`
+      : ` Check the configured base URL, your network connection, or switch model with /model.`;
+    return `Could not connect to ${provider}${target}.${hint}`;
+  }
+  if (isConnectionError(err)) {
+    return `Could not connect to the provider. Check the configured base URL, your network connection, or switch model with /model.`;
+  }
   const msg = (err as Error)?.message ?? String(err);
   const status = (err as { status?: number })?.status;
   const provider = /antigravity/i.test(msg)

package/src/util/retry.ts

@@ -56,6 +56,14 @@ export function defaultRetryable(err: unknown): boolean {
   if (isRefusalError(err)) {
     return false;
   }
+  // A pre-response connection failure (refused / unresolved host) — retryable: a
+  // local provider that is mid-restart, or a transient DNS blip, can clear within
+  // the backoff budget. A provider that is simply never running exhausts the
+  // budget and surfaces friendlyProviderError's actionable message instead of a
+  // bare "Unable to connect" (see isConnectionError's docs for the full rationale).
+  if (isConnectionError(err)) {
+    return true;
+  }
 
   let message = "";
   if (err instanceof Error) {
@@ -312,3 +320,71 @@ export function isRefusalError(err: unknown): boolean {
 export function isTransientStreamDropError(err: unknown): boolean {
   return /socket connection was closed|socket hang up|other side closed|und_err_socket/i.test(errorMessageOf(err));
 }
+
+/** True for a pre-response TCP-level connection failure — the request never reached
+ *  a server at all (refused, DNS unresolved, host unreachable), as opposed to a
+ *  server responding with an error status or a mid-stream drop (see
+ *  `isTransientStreamDropError` for the latter). Bun's fetch/undici throws a bare
+ *  `Error("Unable to connect. Is the computer able to access the url?")` with
+ *  `.code === "ConnectionRefused"` for BOTH a refused connection and an unresolvable
+ *  host — no HTTP status is ever attached, so `defaultRetryable`'s status-based
+ *  checks never catch it. Node's equivalent carries a `.code` of ECONNREFUSED /
+ *  ENOTFOUND / EHOSTUNREACH / EAI_AGAIN. Most commonly hit when a local provider
+ *  (ollama/lmstudio) isn't running, or a custom base URL is misconfigured — see
+ *  `friendlyProviderError`, which turns this into an actionable message naming the
+ *  provider and base URL (attached by model-manager's `resolveCall` callers). */
+export function isConnectionError(err: unknown): boolean {
+  let code: string | undefined;
+  if (err && typeof err === "object" && "code" in err) code = String(err.code);
+  if (code && ["ConnectionRefused", "ECONNREFUSED", "ENOTFOUND", "EHOSTUNREACH", "EAI_AGAIN"].includes(code)) return true;
+  return /unable to connect\. is the computer able to access the url\?/i.test(errorMessageOf(err));
+}
+
+/** A raw `isConnectionError` failure re-thrown with the provider/URL context the bare
+ *  fetch error never carries (see `isConnectionError`'s docs). `.cause` preserves the
+ *  original error so `isConnectionError`/`defaultRetryable` still recognize it (both
+ *  inspect `.code` and the message text, which this class forwards). */
+export class ConnectionContextError extends Error {
+  readonly code: string | undefined;
+  constructor(readonly provider: string, readonly baseUrl: string | undefined, cause: unknown) {
+    const causeCode = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : undefined;
+    super(errorMessageOf(cause), { cause });
+    this.name = "ConnectionContextError";
+    this.code = causeCode;
+  }
+}
+
+/** Run `fn`; a raw `isConnectionError` failure is re-thrown as a `ConnectionContextError`
+ *  naming `provider`/`baseUrl` so `friendlyProviderError` can turn Bun's context-free
+ *  "Unable to connect. Is the computer able to access the url?" into an actionable
+ *  message. Every other error (including a non-connection failure) passes through
+ *  unchanged. */
+export async function withConnectionContext<T>(fn: () => Promise<T>, provider: string, baseUrl: string | undefined): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isConnectionError(err)) throw new ConnectionContextError(provider, baseUrl, err);
+    throw err;
+  }
+}
+
+/** True for an in-band provider stream failure: the HTTP response itself was 200 (a
+ *  live SSE connection), but the provider emitted a terminal error EVENT instead of
+ *  completing (OpenAI Responses `response.failed`/`error`:
+ *  `{"error":{"code":"server_error",...}}`) — see `ProviderStreamError` in
+ *  `ai/providers/errors.ts`. Narrowed via `instanceof Error` + `.name` (not an import
+ *  of the concrete class) to keep this generic util free of a provider-layer
+ *  dependency, mirroring the existing `.name === "TimeoutError"` check in
+ *  `provider-error.ts`. Every instance is treated as retryable here: OpenAI's own
+ *  guidance for the two documented codes (`server_error`, `rate_limit_exceeded`) is
+ *  "retry with exponential backoff", and any other/unenumerated code is rare enough
+ *  that defaulting to retryable beats hard-failing a whole turn on one backend
+ *  hiccup. Note `ProviderStreamError` ALSO carries a numeric `.status` (429/500), so
+ *  `defaultRetryable`'s existing status check already retries it in the
+ *  pre-first-chunk/non-streaming path; this predicate exists for the SEPARATE
+ *  engine-level mid-stream ladder (see `transientNetworkRetries` in engine.ts),
+ *  which — like `isTransientStreamDropError` — deliberately does not call
+ *  `defaultRetryable` there to avoid double-spending that budget. */
+export function isProviderStreamError(err: unknown): boolean {
+  return err instanceof Error && err.name === "ProviderStreamError";
+}