@homeflare/alchemy 0.27.4 → 0.29.0

package/src/caddy/admin-calls.ts

@@ -1,128 +1,76 @@
 /**
- * The three admin API calls the provider makes, each classified into a value or a readable Error
- * that carries Caddy's own message.
+ * The three admin API calls the provider makes, through `@distilled.cloud/caddy`'s typed `admin`
+ * operations — `catchTag`-able errors, never a status check in this file.
  *
  * Read in caddyserver/caddy v2.11.4 (and the API docs, caddyserver.com/docs/api):
- *   · `POST /adapt` — adapts without running (load.go handleAdapt): 200 `{warnings?, result}`,
- *     or 400 `{"error": …}`. Side-effect free, so it is what plan-time validation uses.
- *   · `POST /load` — Content-Type `text/caddyfile` picks the adapter (load.go adaptByContentType);
- *     "if the new config fails for any reason, the old config is rolled back into place without
- *     downtime" (docs; caddy.go changeConfig restores the previous raw config). An identical
- *     config is a no-op without `Cache-Control: must-revalidate`.
- *   · `GET /config/` — the running config as JSON, `null` when empty (admin.go handleConfig).
+ *   · `POST /adapt` (`adaptConfig`) — adapts without running (load.go handleAdapt). Side-effect
+ *     free, so it is what plan-time validation uses.
+ *   · `POST /load` (`loadConfig`) — Content-Type `text/caddyfile` picks the adapter (load.go
+ *     adaptByContentType); "if the new config fails for any reason, the old config is rolled back
+ *     into place without downtime" (docs; caddy.go changeConfig restores the previous raw config).
+ *     An identical config is a no-op without `Cache-Control: must-revalidate`.
+ *   · `GET /config/` (`getConfig`) — the running config as JSON, `null` when empty (admin.go
+ *     handleConfig).
  * ⛔ A FAILED LOAD CAN ANSWER 200. load.go writes the adapter's WARNINGS to the body before it
  *   runs the config; if the run then fails, the error JSON is appended to a response whose status
- *   is already 200 (Go's first Write sends 200; the later WriteHeader(400) is ignored). The
- *   Caddyfile adapter warns on every unformatted input (adapter.go FormattingDifference), so this
- *   is the COMMON failure shape, not an edge. Hence: look for the error in the body whatever the
- *   status — and the lifecycle reads the config back after every load anyway.
- *   MEASURED 2026-09-21 on a throwaway Caddy 2.11.4 (loopback ports, isolated XDG dirs): an
- *   unformatted Caddyfile whose port was taken answered `200` with body
- *   `[{"file":"Caddyfile","line":8,"message":"Caddyfile input is not formatted; …"}]{"error":"loading
- *   config: … bind: address already in use"}`, and Caddy kept serving the previous config.
+ *   is already 200. The Caddyfile adapter warns on every unformatted input (adapter.go
+ *   FormattingDifference), so this is the COMMON failure shape, not an edge. The SDK's own
+ *   `CaddyProtocol` (`packages/distilled-caddy/src/protocol.ts`) scans `loadConfig`'s body for the
+ *   embedded error on every status and fails with the typed `LoadRefused` — `catchTag`'d below,
+ *   never a status check here. The lifecycle also reads the config back after every load anyway
+ *   (config-lifecycle.ts).
  */
-import type { CaddyAdmin, CaddyAdminResponse } from './admin.ts';
-import { parseConfig } from './digest.ts';
-
-export class CaddyAdminError extends Error {
-  constructor(
-    readonly status: number,
-    readonly method: string,
-    readonly path: string,
-    reason: string,
-  ) {
-    super(`Caddy ${method} ${path} → ${String(status)}: ${reason}`);
-    this.name = 'CaddyAdminError';
-  }
-}
+import * as Effect from 'effect/Effect';
+import * as Caddy from '@distilled.cloud/caddy';
 
 const CADDYFILE = 'text/caddyfile';
-/** APIError marshals as exactly this key (admin.go APIError, `json:"error"`). */
-const ERROR_OPEN = '{"error":';
 
-type Warning = { file?: string; line?: number; message?: string };
+type Warning = { readonly file?: string; readonly line?: number; readonly message?: string };
 
 const describe = (warning: Warning): string =>
   `${warning.file ?? 'Caddyfile'}:${String(warning.line ?? 0)}: ${warning.message ?? '(no message)'}`;
 
-/** Caddy's `error` string from a body that holds one, or `undefined`. */
-const errorIn = (body: string): string | undefined => {
-  const at = body.lastIndexOf(ERROR_OPEN);
-  if (at === -1) return undefined;
-  try {
-    const parsed = JSON.parse(body.slice(at)) as { error?: unknown };
-    return typeof parsed.error === 'string' ? parsed.error : undefined;
-  } catch {
-    return undefined;
-  }
-};
-
-const warningsIn = (text: string): string[] => {
-  if (text.trim() === '') return [];
-  try {
-    const parsed = JSON.parse(text) as unknown;
-    return Array.isArray(parsed) ? (parsed as Warning[]).map(describe) : [];
-  } catch {
-    return [];
-  }
-};
-
-const fail = (response: CaddyAdminResponse, method: string, path: string): never => {
-  const reason = errorIn(response.body) ?? (response.body.trim().slice(0, 500) || '(empty body)');
-  // ⚠️ Say so when the status lied (the ⛔ above), or "→ 200" reads like success.
-  const shown = response.status === 200 ? `${reason} (error in a 200 body)` : reason;
-  throw new CaddyAdminError(response.status, method, path, shown);
-};
-
 export type Adapted = { readonly config: unknown; readonly warnings: readonly string[] };
 
 /** Adapt a Caddyfile to JSON on the running Caddy, without loading it. */
-export const adaptCaddyfile = async (admin: CaddyAdmin, caddyfile: string): Promise<Adapted> => {
-  const response = await admin.request({
-    body: caddyfile,
-    headers: { 'Content-Type': CADDYFILE },
-    method: 'POST',
-    path: '/adapt',
-  });
-  // ★ Status alone here: /adapt writes its body once, and a successful result is config JSON in
-  //   which an `error` handler's key could look like an error object to a substring search.
-  if (response.status !== 200) fail(response, 'POST', '/adapt');
-  const parsed = JSON.parse(response.body) as { result?: unknown; warnings?: Warning[] };
-  return { config: parsed.result ?? null, warnings: (parsed.warnings ?? []).map(describe) };
-};
+export const adaptCaddyfile = (
+  caddyfile: string,
+): Effect.Effect<Adapted, Caddy.CaddyOpError, Caddy.CaddyOpContext> =>
+  Effect.map(
+    Caddy.Services.admin.adaptConfig({ config: caddyfile, contentType: CADDYFILE }),
+    (response) => ({
+      config: response.result ?? null,
+      warnings: (response.warnings ?? []).map(describe),
+    }),
+  );
 
 /** The running config, parsed; `null` when Caddy runs with none. */
-export const readRunningConfig = async (admin: CaddyAdmin): Promise<unknown> => {
-  const response = await admin.request({ method: 'GET', path: '/config/' });
-  if (response.status !== 200) fail(response, 'GET', '/config/');
-  return parseConfig(response.body);
-};
+export const readRunningConfig = (): Effect.Effect<
+  unknown,
+  Caddy.CaddyOpError,
+  Caddy.CaddyOpContext
+> => Effect.map(Caddy.Services.admin.getConfig({ path: '' }), (response) => response.value ?? null);
 
 /**
- * Apply a Caddyfile with `POST /load`; resolves with the adapter's warnings.
+ * Apply a Caddyfile with `POST /load`; resolves with the adapter's warnings. A refused load
+ * (`LoadRefused` — the ⛔ above) propagates as that typed error, unretried by anything in this
+ * file — config-lifecycle.ts's `reconcileConfig` is where a refusal turns into a message naming
+ * what is still running.
  *
  * ★ `sourceFile` RIDES AS `Caddy-Config-Source-File` (+ `-Adapter: caddyfile`), the headers
  *   `caddy reload` sends (cmd/commandfuncs.go). A load WITHOUT them makes Caddy forget the file it
  *   was started with (caddy.go ClearLastConfigIfDifferent), and SIGUSR1 then no longer reloads
  *   from that file. With them, and the same path, it keeps it.
  */
-export const loadCaddyfile = async (
-  admin: CaddyAdmin,
+export const loadCaddyfile = (
   caddyfile: string,
   sourceFile?: string,
-): Promise<readonly string[]> => {
-  const response = await admin.request({
-    body: caddyfile,
-    headers: {
-      'Content-Type': CADDYFILE,
-      ...(sourceFile === undefined
-        ? {}
-        : { 'Caddy-Config-Source-Adapter': 'caddyfile', 'Caddy-Config-Source-File': sourceFile }),
-    },
-    method: 'POST',
-    path: '/load',
-  });
-  const refused = errorIn(response.body);
-  if (response.status !== 200 || refused !== undefined) fail(response, 'POST', '/load');
-  return warningsIn(response.body);
-};
+): Effect.Effect<readonly string[], Caddy.CaddyOpError, Caddy.CaddyOpContext> =>
+  Effect.map(
+    Caddy.Services.admin.loadConfig({
+      config: caddyfile,
+      contentType: CADDYFILE,
+      ...(sourceFile === undefined ? {} : { sourceAdapter: 'caddyfile', sourceFile }),
+    }),
+    (response) => (response.warnings ?? []).map(describe),
+  );

package/src/caddy/admin.ts

@@ -1,34 +1,26 @@
 /**
- * The one seam between the Caddy provider and a running Caddy: every call to Caddy's admin API goes
- * through a CaddyAdmin, and nothing in this directory reaches Caddy any other way.
+ * The one seam between the Caddy provider and a running Caddy: every operation goes through
+ * `@distilled.cloud/caddy`'s typed `Services.admin.*` calls (admin-calls.ts), over the
+ * `CaddyAdminService` metadata and the `Credentials` + `HttpClient` layers `localCaddyAdmin()`
+ * builds (local-admin.ts) — nothing in this directory reaches Caddy any other way.
  *
  * ★ CADDY's OWN MANAGEMENT API, NOT A FILE AND A SIGNAL. Decision 23 (vault consolidation plan,
  *   2026-09-21): `POST /load` applies a Caddyfile with a graceful reload and rolls back a config
  *   Caddy refuses; `GET /config/` reports what is running. Read in caddyserver/caddy v2.11.4,
  *   caddyconfig/load.go and admin.go, and in the API docs (caddyserver.com/docs/api).
- * ★ A SEAM, THE SAME SHAPE AS launchd's HostRunner, so the lifecycle runs against a fake admin
- *   server in tests and a consumer can plug in another route to the API (an SSH-forwarded socket
- *   today; a remote runner later) without touching the provider. PROMISES, NOT EFFECTS, for the
- *   same reason as HostRunner: a consumer writing their own implements plain async functions.
+ * ★ `CaddyAdminService` CARRIES ONLY MESSAGE/GUARD METADATA (endpoint, listener) — never a
+ *   credential, and never the transport itself. The transport is `@distilled.cloud/caddy`'s own
+ *   `Credentials` and `HttpClient.HttpClient` services, provided alongside it by `caddyAdminLayer`,
+ *   so admin-calls.ts calls the SDK's operations directly rather than through a house-specific
+ *   `.request()` seam. A consumer plugs in another route to the API (an SSH-forwarded socket today;
+ *   a remote runner later) by providing a different `CaddyTransport` to `caddyAdminLayer`.
  * ⛔ THE ADMIN API HAS NO AUTHENTICATION. Anyone who reaches it can replace every site. It stays on
  *   loopback or a unix socket; localCaddyAdmin() refuses anything else (local-admin.ts).
  */
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
 import * as Context from 'effect/Context';
 import * as Layer from 'effect/Layer';
-
-/** One admin API exchange. ⛔ `body` may hold the running config — never log it whole. */
-export type CaddyAdminResponse = {
-  readonly status: number;
-  readonly body: string;
-};
-
-export type CaddyAdminRequest = {
-  readonly method: 'GET' | 'POST';
-  /** Absolute API path: `/load`, `/adapt`, `/config/`. */
-  readonly path: string;
-  readonly headers?: Readonly<Record<string, string>>;
-  readonly body?: string;
-};
+import type { Credentials } from '@distilled.cloud/caddy';
 
 /**
  * Where the admin listener is, in the terms Caddy's own `admin` option uses — so a Caddyfile that
@@ -38,37 +30,41 @@ export type CaddyAdminListener =
   | { readonly kind: 'tcp'; readonly hostHeader: string; readonly port: number }
   | { readonly kind: 'unix'; readonly path: string };
 
-export interface CaddyAdmin {
-  /** Where requests go, for error messages and the resource's attributes. Never a credential. */
+/** Message/guard metadata for the Caddy this stack talks to — never a credential. */
+export interface CaddyTarget {
+  /** Where requests go, for error messages and the resource's attributes. */
   readonly endpoint: string;
   /**
    * The listener as Caddy sees it. `hostHeader` is the Host every request carries: Caddy checks it
    * against `admin.origins` (admin.go checkHost) on any loopback TCP listener.
    */
   readonly listener: CaddyAdminListener;
-  /**
-   * Send one request. Resolves with ANY status — classifying it is the caller's job
-   * (admin-calls.ts). Rejects only when there was no HTTP exchange at all: with a
-   * CaddyUnreachableError when nothing accepted the connection, any other Error otherwise.
-   */
-  request(request: CaddyAdminRequest): Promise<CaddyAdminResponse>;
 }
 
-/**
- * Nothing accepted the connection — Caddy is not running, or not listening yet. A transport rejects
- * with THIS only when the request provably never reached Caddy (refused, no socket file), because
- * the provider treats it differently from every other failure: a stopped Caddy must not fail the
- * PLAN that would bring it back (its launchd job in the same stack) — see config.ts.
- */
-export class CaddyUnreachableError extends Error {
-  override readonly name = 'CaddyUnreachableError';
+/** What `localCaddyAdmin()` (or a consumer's own transport) hands `caddyAdminLayer`. */
+export interface CaddyTransport extends CaddyTarget {
+  /** Provides the SDK's own `Credentials` and `HttpClient.HttpClient` — see local-admin.ts. */
+  readonly layer: Layer.Layer<Credentials | HttpClient.HttpClient>;
 }
 
-/** The Effect service the Caddy provider reads its admin transport from. */
-export class CaddyAdminService extends Context.Service<CaddyAdminService, CaddyAdmin>()(
+/** The Effect service the Caddy provider reads its admin target's metadata from. */
+export class CaddyAdminService extends Context.Service<CaddyAdminService, CaddyTarget>()(
   'homeflare/caddy/CaddyAdmin',
 ) {}
 
-/** Provide a transport to the provider: `Layer.provide(caddyAdminLayer(localCaddyAdmin()))`. */
-export const caddyAdminLayer = (admin: CaddyAdmin): Layer.Layer<CaddyAdminService> =>
-  Layer.succeed(CaddyAdminService, admin);
+/**
+ * Provide a transport to the provider: `CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(localCaddyAdmin())))`
+ * — never plain `Layer.provide` here (see providers.ts's own ⚠️): `CaddyConfigProvider()`'s handlers
+ * keep needing these services every time the engine calls them, not just once while it is built. Merges
+ * the target metadata with the SDK's `Credentials`/`HttpClient` layers `transport.layer` carries.
+ */
+export const caddyAdminLayer = (
+  transport: CaddyTransport,
+): Layer.Layer<CaddyAdminService | Credentials | HttpClient.HttpClient> =>
+  Layer.mergeAll(
+    Layer.succeed(CaddyAdminService, {
+      endpoint: transport.endpoint,
+      listener: transport.listener,
+    }),
+    transport.layer,
+  );

package/src/caddy/adopt-scope.test.ts

@@ -58,7 +58,7 @@ const applyFirstDeploy = (scope: Scope, flag: boolean) => {
       session: undefined as never,
     });
   }).pipe(
-    Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(made.admin)))),
+    Effect.provide(CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(made.admin)))),
     Effect.provideService(AdoptPolicy, flag),
     Effect.provideService(Stack, spec as never),
   );

package/src/caddy/caddy-http-client.ts

@@ -0,0 +1,229 @@
+/**
+ * An Effect `HttpClient.HttpClient` over `node:http`, dialling a unix socket or loopback TCP
+ * directly — the SDK's own transport layer for `@distilled.cloud/caddy`'s typed operations.
+ *
+ * ★ node:http, NOT `effect/unstable/http/FetchHttpClient`. MEASURED 2026-09-21 on bun 1.4.0 and
+ *   node 26.7.0 (local-admin.ts's history): node:http dials a unix socket on BOTH runtimes, while
+ *   node's fetch has no `unix` option at all (only Bun's does) — `@effect/platform-node`'s own
+ *   `FetchHttpClient`/`NodeHttpClient.makeNodeHttp` (node:http, but URL-only — no `socketPath` seam)
+ *   cannot speak a unix socket either. The published dist loads under node too (launchd's
+ *   local-runner.ts makes the same call for the same reason), so this stays runtime-agnostic.
+ * ★ A CONNECTION NOTHING ACCEPTED IS RETRIED; ONE CADDY ALREADY SAW IS NEVER RE-SENT. Only
+ *   `ECONNREFUSED` (nothing listening) and `ENOENT` (no unix socket file yet) mean the request
+ *   never reached Caddy — a launchd job bootstrapped a moment ago. Anything else (a reset, a
+ *   timeout) may have reached Caddy, so `POST /load` is never resent for it: `isUnreachable`
+ *   (local-admin.ts) is what tells `Caddy.Config`'s plan-time read to proceed without Caddy instead
+ *   of failing the whole plan (config.ts's `planWithoutCaddy`).
+ */
+import * as http from 'node:http';
+import { Readable } from 'node:stream';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Result from 'effect/Result';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import type * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import type { Target } from './admin-address.ts';
+
+export type LocalHttpClientOptions = {
+  /**
+   * Abort an exchange after this long. @default 60_000
+   * ⚠️ A `shutdown_delay` in the Caddyfile makes `/load` block that long (caddyhttp app.go Stop);
+   *   a timeout then fails the deploy while Caddy goes on to apply — the next plan converges.
+   */
+  readonly timeoutMs?: number;
+  /** Retries when the connection is REFUSED — see the module doc. @default 2 */
+  readonly retries?: number;
+  /** @default 500 */
+  readonly retryDelayMs?: number;
+};
+
+const NEVER_CONNECTED = new Set(['ECONNREFUSED', 'ENOENT']);
+
+const codeOf = (cause: unknown): string | undefined =>
+  typeof cause === 'object' && cause !== null && 'code' in cause
+    ? String((cause as { code: unknown }).code)
+    : undefined;
+
+/**
+ * Nothing accepted the connection — see the module doc's ★. A type guard, not just a predicate, so
+ * config-lifecycle.ts's error-wrapping can pass through the raw error unchanged (still typed) and
+ * config.ts's plan-time escape hatch (`Effect.catchIf`) narrows to it directly.
+ */
+export const isUnreachable = (error: unknown): error is HttpClientError.HttpClientError =>
+  error instanceof HttpClientError.HttpClientError &&
+  error.reason._tag === 'TransportError' &&
+  NEVER_CONNECTED.has(codeOf(error.reason.cause) ?? '');
+
+const transportFailure = (request: HttpClientRequest.HttpClientRequest, cause: unknown) =>
+  new HttpClientError.HttpClientError({
+    reason: new HttpClientError.TransportError({ request, cause }),
+  });
+
+/** Node's response headers (string | string[] | undefined) → the single-valued form Web `Response` wants. Caddy never repeats a header this transport reads. */
+const flattenHeaders = (headers: http.IncomingHttpHeaders): Record<string, string> => {
+  const flat: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value !== undefined) flat[key] = Array.isArray(value) ? value.join(', ') : value;
+  }
+  return flat;
+};
+
+const waitForResponse = (
+  nodeRequest: http.ClientRequest,
+  request: HttpClientRequest.HttpClientRequest,
+) =>
+  Effect.callback<http.IncomingMessage, HttpClientError.HttpClientError>((resume) => {
+    const onError = (cause: Error): void => {
+      resume(Effect.fail(transportFailure(request, cause)));
+    };
+    nodeRequest.on('error', onError);
+    const onResponse = (response: http.IncomingMessage): void => {
+      nodeRequest.off('error', onError);
+      resume(Effect.succeed(response));
+    };
+    nodeRequest.on('response', onResponse);
+    return Effect.sync(() => {
+      nodeRequest.off('error', onError);
+      nodeRequest.off('response', onResponse);
+    });
+  });
+
+const waitForFinish = (
+  nodeRequest: http.ClientRequest,
+  request: HttpClientRequest.HttpClientRequest,
+) =>
+  Effect.callback<void, HttpClientError.HttpClientError>((resume) => {
+    const onError = (cause: Error): void => {
+      resume(Effect.fail(transportFailure(request, cause)));
+    };
+    nodeRequest.once('error', onError);
+    const onFinish = (): void => {
+      nodeRequest.off('error', onError);
+      resume(Effect.void);
+    };
+    nodeRequest.once('finish', onFinish);
+    return Effect.sync(() => {
+      nodeRequest.off('error', onError);
+      nodeRequest.off('finish', onFinish);
+    });
+  });
+
+/**
+ * Every Caddy operation's request body is `Empty` (GET/DELETE/`/stop`) or a `Uint8Array` — the
+ * `T.HttpBody()`/JSON-body cascade never produces `Raw`, `FormData` or `Stream` for this SDK
+ * (protocol.ts). A typed refusal, not a defect (S20), for a body shape that would mean the SDK grew
+ * an operation this transport was never taught to send.
+ */
+const sendBody = (
+  nodeRequest: http.ClientRequest,
+  request: HttpClientRequest.HttpClientRequest,
+): Effect.Effect<void, HttpClientError.HttpClientError> =>
+  Effect.suspend(() => {
+    const body = request.body;
+    if (body._tag === 'Empty') {
+      nodeRequest.end();
+      return waitForFinish(nodeRequest, request);
+    }
+    if (body._tag === 'Uint8Array') {
+      // ⚠️ `body.contentLength` is never nullish, so `?? body.body.byteLength` reads as dead code
+      //   to TypeScript's `??` narrowing — which then (a real quirk, not a defect here) infers
+      //   `body` itself as `never` on that unreachable side. Two plain statements instead.
+      nodeRequest.setHeader('content-length', body.contentLength);
+      nodeRequest.end(body.body);
+      return waitForFinish(nodeRequest, request);
+    }
+    return Effect.fail(
+      new HttpClientError.HttpClientError({
+        reason: new HttpClientError.EncodeError({
+          request,
+          description: `Caddy admin transport: unsupported request body "${body._tag}" — every Caddy operation sends Empty or a Uint8Array body`,
+        }),
+      }),
+    );
+  });
+
+const toWebResponse = (source: http.IncomingMessage): Response =>
+  new Response(Readable.toWeb(source) as unknown as ReadableStream, {
+    headers: flattenHeaders(source.headers),
+    status: source.statusCode ?? 0,
+  });
+
+const exchangeOnce = (
+  target: Target,
+  request: HttpClientRequest.HttpClientRequest,
+  url: URL,
+  signal: AbortSignal,
+  timeoutMs: number,
+): Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError> =>
+  Effect.suspend(() => {
+    const nodeRequest = http.request({
+      headers: request.headers,
+      method: request.method,
+      path: `${url.pathname}${url.search}`,
+      signal,
+      timeout: timeoutMs,
+      ...(target.kind === 'unix'
+        ? { socketPath: target.socketPath }
+        : { host: target.host, port: target.port }),
+    });
+    // node:http's own inactivity timeout — a hang (e.g. a `shutdown_delay` blocking `/load`, see
+    // the module doc) destroys the request, which then surfaces through the same 'error' handler
+    // `waitForResponse`/`waitForFinish` already listen on.
+    nodeRequest.on('timeout', () => {
+      nodeRequest.destroy(new Error(`no answer in ${String(timeoutMs)} ms`));
+    });
+    return Effect.raceFirst(
+      waitForResponse(nodeRequest, request),
+      sendBody(nodeRequest, request).pipe(Effect.andThen(Effect.never)),
+    ).pipe(
+      Effect.onError(() => Effect.sync(() => nodeRequest.destroy())),
+      Effect.map((source) => HttpClientResponse.fromWeb(request, toWebResponse(source))),
+    );
+  });
+
+/**
+ * Retry ONLY a connection nothing accepted, up to `retries` times, spaced `retryDelayMs` apart —
+ * a plain loop over `Effect.result`, not `Effect.retry`'s `{schedule, times, while}` options
+ * object. MEASURED 2026-09-23: with a `Schedule` given alongside `times`/`while`, that combined
+ * form retried an ECONNRESET past both — `while` kept correctly returning `false` every attempt,
+ * logged and confirmed, yet the schedule's own unbounded `spaced` kept driving retries anyway. A
+ * loop leaves no such ambiguity: the SAME `isUnreachable` check that would gate `while` here gates
+ * every iteration directly, one attempt at a time.
+ */
+const withUnreachableRetry = (
+  attempt: Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>,
+  retries: number,
+  retryDelayMs: number,
+): Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError> =>
+  Effect.gen(function* () {
+    let attemptsLeft = retries;
+    for (;;) {
+      const outcome = yield* Effect.result(attempt);
+      if (Result.isSuccess(outcome)) return outcome.success;
+      if (attemptsLeft <= 0 || !isUnreachable(outcome.failure)) {
+        return yield* Effect.fail(outcome.failure);
+      }
+      attemptsLeft -= 1;
+      yield* Effect.sleep(Duration.millis(retryDelayMs));
+    }
+  });
+
+/** The transport `localCaddyAdmin()` provides as `HttpClient.HttpClient` — see local-admin.ts. */
+export const makeLocalHttpClient = (
+  target: Target,
+  options: LocalHttpClientOptions = {},
+): Layer.Layer<HttpClient.HttpClient> => {
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const retries = options.retries ?? 2;
+  const retryDelayMs = options.retryDelayMs ?? 500;
+  return Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request, url, signal) => {
+      const attempt = exchangeOnce(target, request, url, signal, timeoutMs);
+      return retries <= 0 ? attempt : withUnreachableRetry(attempt, retries, retryDelayMs);
+    }),
+  );
+};