@vedmalex/ai-connect 0.7.0 → 0.9.0

package/dist/node/index.js

@@ -12,7 +12,10 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
       // pi takes file/image attachments as separate `@<path>` argv tokens (REQ-024);
       // {files} expands one `@<staged-path>` token per attachment. pi stages all
       // categories (PDFs as-is, no extraction guarantee).
-      argsTemplate: ["--print", "--model", "{model}", "{files}", "{prompt}"],
+      // H10 (flag injection): the `--` end-of-options token precedes {files}/{prompt}
+      // — both are BARE positionals here — so an `@<path>` reference or a prompt that
+      // starts with `-` is parsed by pi as a positional, never as a flag.
+      argsTemplate: ["--print", "--model", "{model}", "--", "{files}", "{prompt}"],
       discovery: {
         via: "none"
       },
@@ -32,13 +35,22 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
     transportId: "claude-cli",
     options: {
       preset: "claude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      // H10 (flag injection): `--` precedes the trailing {prompt} positional so a
+      // prompt starting with `-` (e.g. "--dangerously-skip-permissions") is parsed
+      // by the claude CLI as a positional, not a flag.
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "--", "{prompt}"],
       discovery: {
         via: "acp",
         acp: {
           transportId: "claude-code-acp"
         }
       },
+      // SENTINEL (documentation-only): the `__preset__:*` textPath/errorPath values
+      // are NOT resolved as live JSON paths. This `parser` block records which
+      // dedicated parser a built-in preset maps to (parseClaudeCli); dispatch for a
+      // preset route goes through the `cliOptions.preset` switch in cli.ts
+      // (parseCliResult), which only reads a parser config when a ROUTE sets its own
+      // `cli.parser`. See the mirrored note in cli.ts::parseCliResult.
       parser: {
         kind: "json",
         textPath: "__preset__:claude.result",
@@ -54,7 +66,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
     transportId: "openclaude-cli",
     options: {
       preset: "openclaude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      // H10 (flag injection): `--` precedes the trailing {prompt} positional (see
+      // the claude preset above for rationale).
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "--", "{prompt}"],
+      // SENTINEL (documentation-only): see the claude preset note — `__preset__:*`
+      // paths are markers, not live JSON paths; dispatch is via the preset switch.
       parser: {
         kind: "json",
         textPath: "__preset__:claude.result",
@@ -73,6 +89,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
       // codex exec takes image attachments via `-i/--image <FILE>` flags
       // (REQ-024); {files} expands a `--image <staged-path>` pair per image.
       // Images only — a non-image attachment cleanly rejects pre-spawn.
+      // H10 (flag injection): `--` sits AFTER {files} and before the trailing
+      // {prompt} positional. Unlike pi, codex files are passed via the explicit
+      // `--image <path>` flag (the path is that flag's VALUE, not a positional), so
+      // `--` must NOT precede {files} or it would neutralize `--image`. It guards
+      // only the {prompt} positional against being parsed as a flag.
       argsTemplate: [
         "exec",
         "--json",
@@ -81,6 +102,7 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
         "--model",
         "{model}",
         "{files}",
+        "--",
         "{prompt}"
       ],
       discovery: {
@@ -94,6 +116,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
         perFileArgs: ["--image", "{path}"],
         categories: ["image"]
       },
+      // SENTINEL (documentation-only): the `__preset__:*` path values below are
+      // markers naming the dedicated parser this preset maps to (parseCodexCli), NOT
+      // live JSONL selectors. Dispatch for a preset route runs through the
+      // `cliOptions.preset` switch in cli.ts::parseCliResult; this block is only ever
+      // read as a live parser when a ROUTE overrides `cli.parser`.
       parser: {
         kind: "jsonl",
         text: {
@@ -130,6 +157,19 @@ var AiConnectError = class extends Error {
     this.code = code;
     this.details = details;
   }
+  /**
+   * `Error.prototype.message` is non-enumerable, so a bare `JSON.stringify(err)` silently drops
+   * it (LOW, review-report-seed.md). Provide an explicit projection so serializing an
+   * `AiConnectError` (logs, wide events, error-response bodies) always carries the message.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details
+    };
+  }
 };
 function isAiConnectError(error) {
   return error instanceof AiConnectError;
@@ -160,6 +200,16 @@ function toAiConnectError(error, fallbackCode = "temporary_unavailable") {
 // src/config.ts
 var DEFAULT_OPERATIONS = ["text", "image", "file"];
 var DEFAULT_STRATEGY = "priority";
+var CLI_TRANSPORT_ID_BY_PROVIDER = {
+  anthropic: "claude-cli",
+  openclaude: "openclaude-cli",
+  openai: "codex-cli",
+  pi: "pi-cli"
+};
+var ACP_TRANSPORT_ID_BY_PROVIDER = {
+  anthropic: "claude-code-acp",
+  openai: "codex-acp"
+};
 var DEFAULT_FALLBACK_ACTIONS = {
   rate_limit: [
     "rotate-credential",
@@ -271,33 +321,64 @@ function assert(condition, message) {
     throw new AiConnectError("validation_error", message);
   }
 }
-function asPositiveInteger(value, fallback) {
+function asPositiveInteger(value, fallback, fieldLabel) {
+  if (value === void 0) {
+    return fallback;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a positive finite number when provided; received ${JSON.stringify(value)}. Falling back to ${fallback}.`
+      );
+    }
     return fallback;
   }
   return Math.floor(value);
 }
-function asNonNegativeInteger(value, fallback) {
+function asNonNegativeInteger(value, fallback, fieldLabel) {
+  if (value === void 0) {
+    return fallback;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a non-negative finite number when provided; received ${JSON.stringify(value)}. Falling back to ${fallback}.`
+      );
+    }
     return fallback;
   }
   return Math.floor(value);
 }
-function asOptionalContextWindow(value) {
+function asOptionalContextWindow(value, fieldLabel) {
+  if (value === void 0) {
+    return void 0;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a positive finite number when provided; received ${JSON.stringify(value)}. Ignoring.`
+      );
+    }
     return void 0;
   }
   return Math.floor(value);
 }
-function normalizeModelInput(input, accountContextWindow) {
+function normalizeModelInput(input, accountContextWindow, accountId, providerId) {
   if (typeof input === "string") {
     return {
       id: input.trim(),
       ...accountContextWindow !== void 0 ? { contextWindow: accountContextWindow } : {}
     };
   }
+  assert(
+    typeof input.id === "string" && input.id.trim().length > 0,
+    `Account "${accountId}" for provider "${providerId}" declared a model entry with a missing or empty "id".`
+  );
   const id = input.id.trim();
-  const override = asOptionalContextWindow(input.contextWindow);
+  const override = asOptionalContextWindow(
+    input.contextWindow,
+    `Model "${id}" (account "${accountId}", provider "${providerId}") contextWindow`
+  );
   const contextWindow = override ?? accountContextWindow;
   return {
     id,
@@ -308,7 +389,8 @@ function asFanoutBound(value) {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     return Number.POSITIVE_INFINITY;
   }
-  return Math.floor(value);
+  const floored = Math.floor(value);
+  return floored <= 0 ? Number.POSITIVE_INFINITY : floored;
 }
 function normalizeFanoutPolicy(policy) {
   return {
@@ -534,7 +616,7 @@ function normalizeTransport(providerId, input) {
     };
   }
   if (descriptor.kind === "cli") {
-    const inferredId2 = providerId === "anthropic" ? "claude-cli" : providerId === "openclaude" ? "openclaude-cli" : providerId === "openai" ? "codex-cli" : providerId === "pi" ? "pi-cli" : "cli";
+    const inferredId2 = CLI_TRANSPORT_ID_BY_PROVIDER[providerId] ?? "cli";
     return {
       kind: "cli",
       id: descriptor.id?.trim() || inferredId2,
@@ -551,7 +633,7 @@ function normalizeTransport(providerId, input) {
       ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {}
     };
   }
-  const inferredId = providerId === "anthropic" ? "claude-code-acp" : providerId === "openai" ? "codex-acp" : "acp";
+  const inferredId = ACP_TRANSPORT_ID_BY_PROVIDER[providerId] ?? "acp";
   const normalizedLaunch = descriptor.launch ? (() => {
     const contextMode = descriptor.launch?.contextMode ?? "workspace";
     const skillsMode = descriptor.launch?.skillsMode ?? "default";
@@ -648,20 +730,26 @@ function defaultCapabilities(transport, runtime) {
 }
 function normalizeCredential(providerId, accountId, transport, input, index) {
   const id = input.id?.trim() || `${accountId}-credential-${index + 1}`;
-  const source = input.source?.trim() || (input.apiKey ? "literal" : input.apiKeyEnv ? "env" : transport.kind === "api" ? "env" : "session");
+  const trimmedApiKey = input.apiKey?.trim();
+  const trimmedApiKeyEnv = input.apiKeyEnv?.trim();
+  const source = input.source?.trim() || (trimmedApiKey ? "literal" : trimmedApiKeyEnv ? "env" : transport.kind === "api" ? "env" : "session");
   if (transport.kind === "api") {
     assert(
-      Boolean(input.apiKey?.trim()) || Boolean(input.apiKeyEnv?.trim()),
+      Boolean(trimmedApiKey) || Boolean(trimmedApiKeyEnv),
       `API account "${accountId}" for provider "${providerId}" requires apiKey or apiKeyEnv credentials.`
     );
   }
   return {
     id,
     source,
-    weight: asPositiveInteger(input.weight, 1),
+    weight: asPositiveInteger(
+      input.weight,
+      1,
+      `Credential "${id}" (account "${accountId}", provider "${providerId}") weight`
+    ),
     metadata: input.metadata ?? {},
-    ...input.apiKey?.trim() ? { apiKey: input.apiKey.trim() } : {},
-    ...input.apiKeyEnv?.trim() ? { apiKeyEnv: input.apiKeyEnv.trim() } : {},
+    ...trimmedApiKey ? { apiKey: trimmedApiKey } : {},
+    ...trimmedApiKeyEnv ? { apiKeyEnv: trimmedApiKeyEnv } : {},
     ...input.apiKeyDelimiter ? { apiKeyDelimiter: input.apiKeyDelimiter } : {}
   };
 }
@@ -695,6 +783,31 @@ function buildRouteId(route) {
     slugify(route.model)
   ].join(":");
 }
+function assertRouteIdUniqueness(routes) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const group = byId.get(route.id);
+    if (group) {
+      group.push(route);
+    } else {
+      byId.set(route.id, [route]);
+    }
+  }
+  for (const [id, group] of byId) {
+    if (group.length <= 1) {
+      continue;
+    }
+    const distinctModels = [...new Set(group.map((route) => route.model))];
+    if (distinctModels.length <= 1) {
+      continue;
+    }
+    const first = group[0];
+    assert(
+      false,
+      `Route id "${id}" is ambiguous: model(s) ${distinctModels.map((model) => `"${model}"`).join(", ")} on account "${first.accountId}" (provider "${first.provider}") slugify to the same route id. Rename one of the models so they no longer collide after slugification.`
+    );
+  }
+}
 function routeAliases(route) {
   return [
     route.provider,
@@ -819,7 +932,8 @@ function defineConfig(input) {
       const transport = normalizeTransport(providerId, accountInput.transport);
       const runtime = normalizeRuntime(transport, accountInput.runtime);
       const accountContextWindow = asOptionalContextWindow(
-        accountInput.contextWindow
+        accountInput.contextWindow,
+        `Account "${accountId}" (provider "${providerId}") contextWindow`
       );
       const accountModelAllowlistMode = accountInput.modelAllowlistMode ?? "strict";
       const accountContextMode = accountInput.contextMode ?? "workspace";
@@ -829,7 +943,9 @@ function defineConfig(input) {
         Array.isArray(accountInput.models) && accountInput.models.length > 0,
         `Account "${accountId}" for provider "${providerId}" must declare at least one model.`
       );
-      const models = accountInput.models.map((model) => normalizeModelInput(model, accountContextWindow)).filter((model) => model.id.length > 0);
+      const models = accountInput.models.map(
+        (model) => normalizeModelInput(model, accountContextWindow, accountId, providerId)
+      ).filter((model) => model.id.length > 0);
       assert(
         models.length > 0,
         `Account "${accountId}" for provider "${providerId}" must declare at least one model.`
@@ -859,8 +975,16 @@ function defineConfig(input) {
         credentials,
         capabilities,
         verify,
-        weight: asPositiveInteger(accountInput.weight, 1),
-        priority: asNonNegativeInteger(accountInput.priority, accountIndex),
+        weight: asPositiveInteger(
+          accountInput.weight,
+          1,
+          `Account "${accountId}" (provider "${providerId}") weight`
+        ),
+        priority: asNonNegativeInteger(
+          accountInput.priority,
+          accountIndex,
+          `Account "${accountId}" (provider "${providerId}") priority`
+        ),
         enabled: accountInput.enabled ?? true
       };
       accounts.push(normalizedAccount);
@@ -907,6 +1031,7 @@ function defineConfig(input) {
     };
   }
   assert(routes.length > 0, "At least one enabled route must be produced.");
+  assertRouteIdUniqueness(routes);
   finalizeRotationCapabilities(routes);
   const strategy = input.routing?.strategy ?? DEFAULT_STRATEGY;
   const resolutionInput = input.routing?.resolution;
@@ -980,6 +1105,10 @@ function resolveRouteSelectors(selectors, routes, policy) {
 }
 
 // src/fanout.ts
+function abortedError() {
+  return new AiConnectError("aborted", "Operation aborted.");
+}
+var MAX_DELAY_MS = 24 * 60 * 60 * 1e3;
 function createFanoutLimiter(policy, runtime) {
   const now = () => runtime.now?.() ?? Date.now();
   const { maxConcurrency, requestsPerSecond, maxCalls } = policy;
@@ -1043,10 +1172,10 @@ function createFanoutLimiter(policy, runtime) {
           if (index >= 0) {
             concurrencyQueue.splice(index, 1);
           }
-          rejectWaiter(waiter, new AiConnectError("aborted", "Operation aborted."));
+          rejectWaiter(waiter, abortedError());
         };
         if (signal.aborted) {
-          reject(new AiConnectError("aborted", "Operation aborted."));
+          reject(abortedError());
           return;
         }
         waiter.signal = signal;
@@ -1062,7 +1191,7 @@ function createFanoutLimiter(policy, runtime) {
     }
     while (true) {
       if (signal?.aborted) {
-        throw new AiConnectError("aborted", "Operation aborted.");
+        throw abortedError();
       }
       refill();
       if (tokens >= 1) {
@@ -1074,6 +1203,7 @@ function createFanoutLimiter(policy, runtime) {
     }
   }
   function delay(ms, signal) {
+    const safeMs = Number.isFinite(ms) && ms >= 0 ? Math.min(ms, MAX_DELAY_MS) : MAX_DELAY_MS;
     return new Promise((resolve, reject) => {
       let cancelTimer;
       const onAbort = () => {
@@ -1081,11 +1211,11 @@ function createFanoutLimiter(policy, runtime) {
         if (signal) {
           signal.removeEventListener("abort", onAbort);
         }
-        reject(new AiConnectError("aborted", "Operation aborted."));
+        reject(abortedError());
       };
       if (signal) {
         if (signal.aborted) {
-          reject(new AiConnectError("aborted", "Operation aborted."));
+          reject(abortedError());
           return;
         }
         signal.addEventListener("abort", onAbort, { once: true });
@@ -1097,9 +1227,9 @@ function createFanoutLimiter(policy, runtime) {
         resolve();
       };
       if (runtime.setTimer) {
-        cancelTimer = runtime.setTimer(ms, done);
+        cancelTimer = runtime.setTimer(safeMs, done);
       } else {
-        const handle = setTimeout(done, ms);
+        const handle = setTimeout(done, safeMs);
         cancelTimer = () => clearTimeout(handle);
       }
     });
@@ -1113,8 +1243,13 @@ function createFanoutLimiter(policy, runtime) {
         );
       }
       callsStarted += 1;
-      await awaitRateToken(signal);
-      await awaitConcurrencySlot(signal);
+      try {
+        await awaitRateToken(signal);
+        await awaitConcurrencySlot(signal);
+      } catch (error) {
+        callsStarted -= 1;
+        throw error;
+      }
       let released = false;
       return () => {
         if (released) {
@@ -1202,19 +1337,54 @@ function isRemoteUrl(value) {
     return false;
   }
 }
+function mimeTypeAndExtensionFromMediaType(mediaTypeAndParams, fallbackMimeType, fallbackExtension) {
+  const mimeType = mediaTypeAndParams.split(";")[0]?.trim() || fallbackMimeType;
+  const extension2 = mimeType.split("/")[1] ?? fallbackExtension;
+  return { mimeType, extension: extension2 };
+}
 function parseDataUrl(value) {
-  const match = /^data:([^,]*?);base64,(.*)$/i.exec(value);
-  if (!match) {
-    return null;
+  const base64Match = /^data:([^,]*?);base64,(.*)$/i.exec(value);
+  if (base64Match) {
+    const { mimeType, extension: extension2 } = mimeTypeAndExtensionFromMediaType(
+      base64Match[1] ?? "",
+      "application/octet-stream",
+      "bin"
+    );
+    return {
+      mimeType,
+      extension: extension2,
+      data: base64Match[2] ?? ""
+    };
   }
-  const mediaTypeAndParams = match[1] ?? "";
-  const mimeType = mediaTypeAndParams.split(";")[0]?.trim() || "application/octet-stream";
-  const extension2 = mimeType.split("/")[1] ?? "bin";
-  return {
-    mimeType,
-    extension: extension2,
-    data: match[2] ?? ""
-  };
+  const plainMatch = /^data:([^,]*?),(.*)$/i.exec(value);
+  if (plainMatch) {
+    const { mimeType, extension: extension2 } = mimeTypeAndExtensionFromMediaType(
+      plainMatch[1] ?? "",
+      "text/plain",
+      "txt"
+    );
+    let decoded;
+    try {
+      decoded = decodeURIComponent(plainMatch[2] ?? "");
+    } catch {
+      throw new AiConnectError(
+        "validation_error",
+        "unsupported data URL encoding"
+      );
+    }
+    return {
+      mimeType,
+      extension: extension2,
+      data: encodeBase64(new TextEncoder().encode(decoded))
+    };
+  }
+  if (/^data:/i.test(value)) {
+    throw new AiConnectError(
+      "validation_error",
+      "unsupported data URL encoding"
+    );
+  }
+  return null;
 }
 function mimeTypeFromName(name) {
   const ext = extension(name);
@@ -1428,9 +1598,61 @@ async function materializePortableFile(file) {
       payload.dataUrl = `data:${mimeType};base64,${base64}`;
     }
   }
+  if (category === "other") {
+    const base64 = await portableFileToBase64(file);
+    if (base64 !== void 0) {
+      payload.base64 = base64;
+      payload.dataUrl = `data:${mimeType};base64,${base64}`;
+    } else if (!uri && !providerFileId) {
+      const droppedReason = `Portable file "${file.name}" (category "other", kind "${file.kind}") has no decodable byte source and no remote uri/providerFileId; its content was dropped and this payload carries metadata only.`;
+      payload.droppedReason = droppedReason;
+      payload.warnings = [...payload.warnings ?? [], droppedReason];
+    }
+  }
   return payload;
 }
-function preparePortableFile(input) {
+function collapsePathSegments(value) {
+  const normalized = value.replaceAll("\\", "/");
+  const isAbsolute = normalized.startsWith("/");
+  const segments = normalized.split("/");
+  const resolved = [];
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (resolved.length > 0 && resolved[resolved.length - 1] !== "..") {
+        resolved.pop();
+      } else if (!isAbsolute) {
+        resolved.push("..");
+      }
+      continue;
+    }
+    resolved.push(segment);
+  }
+  return (isAbsolute ? "/" : "") + resolved.join("/");
+}
+function applyPathGuard(rawPath, guard) {
+  if (!guard) {
+    return rawPath;
+  }
+  if (guard === "basename") {
+    return basename(rawPath);
+  }
+  const resolved = collapsePathSegments(rawPath);
+  const withinAllowedRoot = guard.allowedRoots.some((root) => {
+    const resolvedRoot = collapsePathSegments(root);
+    return resolved === resolvedRoot || resolved.startsWith(`${resolvedRoot}/`);
+  });
+  if (!withinAllowedRoot) {
+    throw new AiConnectError(
+      "validation_error",
+      `Path "${rawPath}" is outside the configured allowedRoots for portable file attachments.`
+    );
+  }
+  return rawPath;
+}
+function preparePortableFile(input, options) {
   if (isPortableFile(input)) {
     return input;
   }
@@ -1456,11 +1678,12 @@ function preparePortableFile(input) {
         }
       };
     }
+    const guardedPath = applyPathGuard(input, options?.pathGuard);
     return {
-      id: `path:${input}`,
+      id: `path:${guardedPath}`,
       kind: "path",
-      name: basename(input),
-      source: input
+      name: basename(guardedPath),
+      source: guardedPath
     };
   }
   if (isRemoteReference(input)) {
@@ -1501,17 +1724,76 @@ function preparePortableFile(input) {
 }
 
 // src/logging.ts
+var REDACT_KEYS = /* @__PURE__ */ new Set([
+  "apikey",
+  "authorization",
+  "password",
+  "token",
+  "x-api-key",
+  "x-goog-api-key"
+]);
+var REDACTED = "[REDACTED]";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var SECRET_PREFIX_RE = /^(sk-|sk-ant-|xox[baprs]-|ghp_|gho_|AIza)/;
+function looksLikeSecretValue(value) {
+  if (UUID_RE.test(value)) {
+    return false;
+  }
+  if (/^Bearer\s+/i.test(value)) {
+    return true;
+  }
+  if (SECRET_PREFIX_RE.test(value)) {
+    return true;
+  }
+  return /^[A-Za-z0-9+/=_]{40,}$/.test(value);
+}
+function redactNode(node) {
+  if (node === null || node === void 0) {
+    return node;
+  }
+  if (typeof node === "string") {
+    return looksLikeSecretValue(node) ? REDACTED : node;
+  }
+  if (typeof node !== "object") {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => redactNode(item));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = REDACT_KEYS.has(key.toLowerCase()) ? REDACTED : redactNode(value);
+  }
+  return result;
+}
+function redactEvent(event) {
+  return redactNode(event);
+}
+function redactBaseUrl(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    const withoutHash = url.split("#")[0] ?? url;
+    return withoutHash.split("?")[0] ?? withoutHash;
+  }
+}
 function createConsoleWideEventLogger(options = {}) {
   const write = options.write ?? ((line) => {
     console.info(line);
   });
   return (event) => {
+    const redacted = redactEvent(event);
     write(
-      options.pretty ? JSON.stringify(event, null, 2) : JSON.stringify(event)
+      options.pretty ? JSON.stringify(redacted, null, 2) : JSON.stringify(redacted)
     );
   };
 }
-async function shouldEmitWideEvent(event, options = {}) {
+async function shouldEmitWideEvent(event, options = {}, random = Math.random) {
   const sampleRate = options.sampleRate ?? 1;
   if ((options.keepErrors ?? true) && event.outcome === "error") {
     return true;
@@ -1545,7 +1827,7 @@ async function shouldEmitWideEvent(event, options = {}) {
   if (sampleRate >= 1) {
     return true;
   }
-  return Math.random() < sampleRate;
+  return random() < sampleRate;
 }
 
 // src/router.ts
@@ -1610,6 +1892,19 @@ function buildWeightedOrder(routes) {
   }
   return expanded;
 }
+var ROUTING_STRATEGIES = {
+  priority: (ordered) => ordered,
+  failover: (ordered) => ordered,
+  "round-robin": (ordered, cursor, cursorKey) => {
+    const index = cursor(cursorKey, ordered.length);
+    return rotate(ordered, index);
+  },
+  "weighted-round-robin": (ordered, cursor, cursorKey) => {
+    const weighted = buildWeightedOrder(ordered);
+    const index = cursor(cursorKey, weighted.length);
+    return unique(rotate(weighted, index));
+  }
+};
 var RouteRegistry = class {
   config;
   runtime;
@@ -1680,14 +1975,21 @@ var RouteRegistry = class {
     const routeIds = request.routeHints?.pool?.length ? resolveRouteSelectors(request.routeHints.pool, this.config.routes) : operationRouting.pool;
     const excludedIds = new Set(request.routeHints?.excludeRouteIds ?? []);
     const requestedModel = request.routeHints?.model;
-    const available = routeIds.map((routeId) => this.#routeMap.get(routeId)).filter((route) => Boolean(route)).filter((route) => !excludedIds.has(route.id)).filter((route) => runtimeEligible(route, this.runtime)).filter((route) => capabilityMatch(route, request.routeHints)).filter((route) => {
-      const state = this.getHealth(route).state;
-      return state !== "cooling_down" && state !== "unavailable";
-    }).map((route) => applyRequestedModel(route, requestedModel)).filter((route) => Boolean(route));
+    const eligible = routeIds.map((routeId) => this.#routeMap.get(routeId)).filter((route) => Boolean(route)).filter((route) => !excludedIds.has(route.id)).filter((route) => runtimeEligible(route, this.runtime)).filter((route) => capabilityMatch(route, request.routeHints)).map((route) => applyRequestedModel(route, requestedModel)).filter((route) => Boolean(route));
+    const strategy = request.routeHints?.strategy ?? operationRouting.strategy;
+    const cursorKey = `${operation}:${strategy}:${eligible.map((route) => route.id).join("|")}`;
+    const healthyIds = new Set(
+      eligible.filter((route) => {
+        const state = this.getHealth(route).state;
+        return state !== "cooling_down" && state !== "unavailable";
+      }).map((route) => route.id)
+    );
     return this.#order(
-      request.routeHints?.strategy ?? operationRouting.strategy,
-      available,
-      request.routeHints?.preferredProviders
+      strategy,
+      eligible,
+      healthyIds,
+      request.routeHints?.preferredProviders,
+      cursorKey
     );
   }
   recordSuccess(route) {
@@ -1720,20 +2022,12 @@ var RouteRegistry = class {
       failureCount
     });
   }
-  #order(strategy, routes, preferredProviders) {
-    const sorted = baseSort(routes, preferredProviders);
-    const cursorKey = `${strategy}:${sorted.map((route) => route.id).join("|")}`;
-    const ordered = this.config.routing.shuffleOnInit ? this.#shuffle(cursorKey, sorted) : sorted;
-    if (strategy === "priority" || strategy === "failover") {
-      return ordered;
-    }
-    if (strategy === "round-robin") {
-      const index2 = this.#cursor(cursorKey, ordered.length);
-      return rotate(ordered, index2);
-    }
-    const weighted = buildWeightedOrder(ordered);
-    const index = this.#cursor(cursorKey, weighted.length);
-    return unique(rotate(weighted, index));
+  #order(strategy, eligible, healthyIds, preferredProviders, cursorKey) {
+    const sorted = baseSort(eligible, preferredProviders);
+    const orderedFull = this.config.routing.shuffleOnInit ? this.#shuffle(cursorKey, sorted) : sorted;
+    const ordered = orderedFull.filter((route) => healthyIds.has(route.id));
+    const strategyFn = ROUTING_STRATEGIES[strategy];
+    return strategyFn(ordered, (key, length) => this.#cursor(key, length), cursorKey);
   }
   #shuffle(key, routes) {
     const cached = this.#shuffles.get(key);
@@ -1837,8 +2131,22 @@ var MODEL_REFERENCE = {
   "gemini-1.5-flash": { key: "gemini-1.5-flash", contextLength: 1048576 },
   "gemini-1.5-pro": { key: "gemini-1.5-pro", contextLength: 2097152 }
 };
+var REASONING_EFFORT_SUFFIXES = /* @__PURE__ */ new Set([
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh"
+]);
 function normalizeModelKey(model) {
   let key = model.trim().toLowerCase();
+  const lastSlashIndex = key.lastIndexOf("/");
+  if (lastSlashIndex > 0 && lastSlashIndex < key.length - 1) {
+    const tail = key.slice(lastSlashIndex + 1);
+    if (REASONING_EFFORT_SUFFIXES.has(tail)) {
+      key = key.slice(0, lastSlashIndex);
+    }
+  }
   const slashIndex = key.indexOf("/");
   if (slashIndex > 0) {
     key = key.slice(slashIndex + 1);
@@ -1846,6 +2154,7 @@ function normalizeModelKey(model) {
   key = key.replace(/:(?:free|beta)$/i, "");
   return key.trim();
 }
+var MIN_SUBSTRING_MATCH_KEY_LENGTH = 4;
 function lookupModelRef(model) {
   const normalized = normalizeModelKey(model);
   if (!normalized) {
@@ -1868,7 +2177,7 @@ function lookupModelRef(model) {
   }
   let substringWinner;
   for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
-    if (normalized.includes(key)) {
+    if (key.length >= MIN_SUBSTRING_MATCH_KEY_LENGTH && normalized.includes(key)) {
       if (!substringWinner || key.length > substringWinner.key.length) {
         substringWinner = entry;
       }
@@ -2103,6 +2412,14 @@ var DEFAULT_LOGGING_SERVICE = "ai-connect";
 function splitCredentialValues(value, delimiter2) {
   return value.split(delimiter2).map((item) => item.trim()).filter(Boolean);
 }
+var ClientToolExecutionError = class extends Error {
+  aiError;
+  constructor(aiError) {
+    super(aiError.message);
+    this.name = "ClientToolExecutionError";
+    this.aiError = aiError;
+  }
+};
 function materializeRuntimeConfig(config, runtime) {
   const routeExpansion = /* @__PURE__ */ new Map();
   const routes = [];
@@ -2117,13 +2434,14 @@ function materializeRuntimeConfig(config, runtime) {
       continue;
     }
     const expandedIds = [];
+    const expandedWeight = Math.max(1, Math.floor(route.weight / values.length));
     values.forEach((apiKey, index) => {
       const credentialId = `${route.credentialId}#${index + 1}`;
       const expandedRoute = {
         ...route,
         id: `${route.id}#${index + 1}`,
         credentialId,
-        weight: 1,
+        weight: expandedWeight,
         credential: {
           ...route.credential,
           id: credentialId,
@@ -2164,6 +2482,27 @@ async function sleep(delayMs) {
   }
   await new Promise((resolve) => setTimeout(resolve, delayMs));
 }
+async function runWithAbortRace(handlerPromise, abort) {
+  if (abort.signal.aborted) {
+    void Promise.resolve(handlerPromise).catch(() => {
+    });
+    throw mapAbortError(abort.reason);
+  }
+  let onAbort;
+  const abortPromise = new Promise((_, reject) => {
+    onAbort = () => reject(mapAbortError(abort.reason));
+    abort.signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([handlerPromise, abortPromise]);
+  } finally {
+    if (onAbort) {
+      abort.signal.removeEventListener("abort", onAbort);
+    }
+    void Promise.resolve(handlerPromise).catch(() => {
+    });
+  }
+}
 function normalizeWorkingDirectory(value) {
   if (value === void 0) {
     return void 0;
@@ -2205,6 +2544,12 @@ function normalizeClientToolRegistry(tools) {
   const registry = /* @__PURE__ */ new Map();
   for (const tool of tools ?? []) {
     const normalized = normalizeClientToolDefinition(tool);
+    if (registry.has(normalized.function.name)) {
+      throw new AiConnectError(
+        "validation_error",
+        `Duplicate client tool name "${normalized.function.name}" registered on this client.`
+      );
+    }
     registry.set(normalized.function.name, normalized);
   }
   return registry;
@@ -2230,10 +2575,22 @@ function resolveClientToolSelections(selections, registry) {
           `No client tool named "${name}" is registered on this client.`
         );
       }
+      if (resolved.has(name)) {
+        throw new AiConnectError(
+          "validation_error",
+          `Duplicate client tool "${name}" in the clientTools selection.`
+        );
+      }
       resolved.set(name, registered);
       continue;
     }
     const normalized = normalizeClientToolDefinition(selection);
+    if (resolved.has(normalized.function.name)) {
+      throw new AiConnectError(
+        "validation_error",
+        `Duplicate client tool "${normalized.function.name}" in the clientTools selection.`
+      );
+    }
     resolved.set(normalized.function.name, normalized);
   }
   return Array.from(resolved.values());
@@ -2346,6 +2703,34 @@ function requiresImageInput(request) {
 function requiresFileUpload(request) {
   return request.attachments.some((file) => isPortableDocumentFile(file));
 }
+function resolveRequiredCapabilities(request) {
+  const requiresSchema = requiresToolSchema(request);
+  const requiresClientTools = requiresClientToolExecution(request);
+  const requiresImage = requiresImageInput(request);
+  const requiresFile = requiresFileUpload(request);
+  const requiresAnyCapability = requiresSchema || requiresClientTools || requiresImage || requiresFile;
+  const projected = requiresAnyCapability ? {
+    ...request,
+    routeHints: {
+      ...request.routeHints ?? {},
+      requiredCapabilities: {
+        ...request.routeHints?.requiredCapabilities ?? {},
+        ...requiresSchema ? { supportsToolSchema: true } : {},
+        ...requiresClientTools ? { supportsClientToolExecution: true } : {},
+        ...requiresImage ? { supportsImageInput: true } : {},
+        ...requiresFile ? { supportsFileUpload: true } : {}
+      }
+    }
+  } : request;
+  return {
+    requiresSchema,
+    requiresClientTools,
+    requiresImage,
+    requiresFile,
+    requiresAnyCapability,
+    request: projected
+  };
+}
 function normalizeRequestBase(request) {
   if (request.messages.length === 0) {
     throw new AiConnectError("validation_error", "Unified generate/stream requests must include at least one message.");
@@ -2554,7 +2939,10 @@ function summarizeRoute(route) {
     model: route.model,
     handlerKey: route.handlerKey,
     profileId: route.profileId,
-    ...route.transport.baseUrl ? { baseUrl: route.transport.baseUrl } : {}
+    // SYS-3 / C1a: never emit a raw baseUrl into a wide event — a token embedded in
+    // userinfo (`https://user:secret@host`) or the query string would leak verbatim,
+    // unlike the secret-safe toPublicRoute projection. Strip credentials first.
+    ...route.transport.baseUrl ? { baseUrl: redactBaseUrl(route.transport.baseUrl) } : {}
   };
 }
 function summarizeFiles(files) {
@@ -2865,21 +3253,40 @@ function createClient(configOrInput, options = {}) {
       for (const toolCall of toolCalls) {
         const tool = registry.get(toolCall.name);
         if (!tool) {
-          throw new AiConnectError(
-            "validation_error",
-            `No client tool handler is registered for "${toolCall.name}".`
+          throw new ClientToolExecutionError(
+            new AiConnectError(
+              "validation_error",
+              `No client tool handler is registered for "${toolCall.name}".`
+            )
+          );
+        }
+        if (abort.signal.aborted) {
+          throw mapAbortError(abort.reason);
+        }
+        let execution;
+        try {
+          execution = normalizeToolResult(
+            await tool.execute(toolCall.arguments, {
+              route,
+              request,
+              runtime,
+              toolCall,
+              messages,
+              ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
+            })
+          );
+        } catch (error) {
+          if (abort.signal.aborted) {
+            throw mapAbortError(abort.reason);
+          }
+          throw new ClientToolExecutionError(
+            new AiConnectError(
+              "validation_error",
+              `Client tool "${tool.function.name}" threw during execution: ${error instanceof Error ? error.message : String(error)}`,
+              { cause: error }
+            )
           );
         }
-        const execution = normalizeToolResult(
-          await tool.execute(toolCall.arguments, {
-            route,
-            request,
-            runtime,
-            toolCall,
-            messages,
-            ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
-          })
-        );
         toolMessages.push({
           role: "tool",
           content: execution.content,
@@ -2893,28 +3300,33 @@ function createClient(configOrInput, options = {}) {
       if (abort.signal.aborted) {
         throw mapAbortError(abort.reason);
       }
-      output = await handler({
-        route,
-        request: {
-          ...request,
-          messages,
-          attachments: []
-        },
-        runtime,
-        attempt: baseAttempt,
-        abort,
-        telemetry: {
-          captureTransport(summary) {
-            transportSummary2 = summary;
+      output = await runWithAbortRace(
+        handler({
+          route,
+          request: {
+            ...request,
+            messages,
+            attachments: []
+          },
+          runtime,
+          attempt: baseAttempt,
+          abort,
+          telemetry: {
+            captureTransport(summary) {
+              transportSummary2 = summary;
+            }
           }
-        }
-      });
+        }),
+        abort
+      );
       warnings.push(...output.warnings ?? []);
       usage = mergeUsage(usage, output.usage);
     }
-    throw new AiConnectError(
-      "validation_error",
-      "clientTools exceeded the maximum tool-call loop depth of 8."
+    throw new ClientToolExecutionError(
+      new AiConnectError(
+        "validation_error",
+        "clientTools exceeded the maximum tool-call loop depth of 8."
+      )
     );
   }
   async function emitWideEvent(event) {
@@ -2945,26 +3357,8 @@ function createClient(configOrInput, options = {}) {
   async function executeGenerateOperation(normalizedRequest, operationName, abort, seed = {}) {
     const startedAt = seed.startMs ?? nowMs(runtime);
     const requestId = seed.requestId ?? resolveEventRequestId(normalizedRequest.logContext);
-    const requiresSchema = requiresToolSchema(normalizedRequest);
-    const requiresClientTools = requiresClientToolExecution(normalizedRequest);
-    const requiresImage = requiresImageInput(normalizedRequest);
-    const requiresFile = requiresFileUpload(normalizedRequest);
-    const requiresAnyCapability = requiresSchema || requiresClientTools || requiresImage || requiresFile;
-    const resolvedCandidates = router.resolveCandidates(
-      requiresAnyCapability ? {
-        ...normalizedRequest,
-        routeHints: {
-          ...normalizedRequest.routeHints ?? {},
-          requiredCapabilities: {
-            ...normalizedRequest.routeHints?.requiredCapabilities ?? {},
-            ...requiresSchema ? { supportsToolSchema: true } : {},
-            ...requiresClientTools ? { supportsClientToolExecution: true } : {},
-            ...requiresImage ? { supportsImageInput: true } : {},
-            ...requiresFile ? { supportsFileUpload: true } : {}
-          }
-        }
-      } : normalizedRequest
-    );
+    const { requiresImage, requiresFile, request: capabilityScopedRequest } = resolveRequiredCapabilities(normalizedRequest);
+    const resolvedCandidates = router.resolveCandidates(capabilityScopedRequest);
     const candidates = seed.candidates ?? resolvedCandidates.map(summarizeRoute);
     const requestSummary = summarizeRequest(normalizedRequest, candidates);
     if (resolvedCandidates.length === 0) {
@@ -3052,18 +3446,21 @@ function createClient(configOrInput, options = {}) {
         const attemptStartedAt = nowMs(runtime);
         let transportSummary2;
         try {
-          let output = await handler.generate({
-            route,
-            request: routeRequest,
-            runtime,
-            attempt: attempts.length + 1,
-            abort,
-            telemetry: {
-              captureTransport(summary) {
-                transportSummary2 = summary;
+          let output = await runWithAbortRace(
+            handler.generate({
+              route,
+              request: routeRequest,
+              runtime,
+              attempt: attempts.length + 1,
+              abort,
+              telemetry: {
+                captureTransport(summary) {
+                  transportSummary2 = summary;
+                }
               }
-            }
-          });
+            }),
+            abort
+          );
           if (routeRequest.clientTools?.length && output.toolCalls?.length) {
             const loopResult = await executeClientToolLoop(
               route,
@@ -3078,6 +3475,9 @@ function createClient(configOrInput, options = {}) {
               transportSummary2 = loopResult.transportSummary;
             }
           }
+          if (abort.signal.aborted) {
+            throw mapAbortError(abort.reason);
+          }
           wideAttempts.push({
             index: wideAttempts.length + 1,
             route: routeSummary,
@@ -3148,6 +3548,49 @@ function createClient(configOrInput, options = {}) {
               routeId: route.id
             });
           }
+          if (error instanceof ClientToolExecutionError) {
+            const toolError = error.aiError;
+            attempts.push({
+              routeId: route.id,
+              handlerKey: route.handlerKey,
+              errorCode: toolError.code,
+              message: toolError.message
+            });
+            wideAttempts.push({
+              index: wideAttempts.length + 1,
+              route: routeSummary,
+              durationMs: nowMs(runtime) - attemptStartedAt,
+              outcome: "error",
+              retryCount,
+              errorCode: toolError.code,
+              message: toolError.message,
+              ...transportSummary2 ? { transport: transportSummary2 } : {}
+            });
+            await emitWideEvent({
+              timestamp: isoTimestamp(startedAt),
+              event: "ai_connect.operation",
+              requestId,
+              operationName,
+              operation: normalizedRequest.operation,
+              runtime: runtime.kind,
+              outcome: "error",
+              durationMs: nowMs(runtime) - startedAt,
+              candidates,
+              attempts: wideAttempts,
+              request: requestSummary,
+              error: {
+                code: toolError.code,
+                message: toolError.message,
+                routeId: route.id
+              },
+              ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+            });
+            throw new AiConnectError(toolError.code, toolError.message, {
+              ...toolError.details,
+              attempts,
+              routeId: route.id
+            });
+          }
           const normalizedError = toAiConnectError(error);
           const actions = config.routing.fallback.on[normalizedError.code] ?? [];
           attempts.push({
@@ -3392,30 +3835,16 @@ function createClient(configOrInput, options = {}) {
     return report;
   }
   async function runPingWithAbort(route, handler, abort) {
-    if (abort.signal.aborted) {
-      throw mapAbortError(abort.reason);
-    }
-    const handlerPromise = handler({
-      route,
-      request: buildPingRequest(),
-      runtime,
-      attempt: 1,
+    return runWithAbortRace(
+      handler({
+        route,
+        request: buildPingRequest(),
+        runtime,
+        attempt: 1,
+        abort
+      }),
       abort
-    });
-    let onAbort;
-    const abortPromise = new Promise((_, reject) => {
-      onAbort = () => reject(mapAbortError(abort.reason));
-      abort.signal.addEventListener("abort", onAbort, { once: true });
-    });
-    try {
-      return await Promise.race([handlerPromise, abortPromise]);
-    } finally {
-      if (onAbort) {
-        abort.signal.removeEventListener("abort", onAbort);
-      }
-      void Promise.resolve(handlerPromise).catch(() => {
-      });
-    }
+    );
   }
   async function checkEndpointReachable(route, handler, abort) {
     if (abort.signal.aborted) {
@@ -3983,19 +4412,8 @@ function createClient(configOrInput, options = {}) {
         release = await limiter.acquire(abort.signal);
         const selectedModel = await resolveSelectedModel(preparedRequest);
         const normalizedRequest = withSelectedModel(preparedRequest, selectedModel);
-        const requiresSchema = requiresToolSchema(normalizedRequest);
-        const candidates = router.resolveCandidates(
-          requiresSchema ? {
-            ...normalizedRequest,
-            routeHints: {
-              ...normalizedRequest.routeHints ?? {},
-              requiredCapabilities: {
-                ...normalizedRequest.routeHints?.requiredCapabilities ?? {},
-                supportsToolSchema: true
-              }
-            }
-          } : normalizedRequest
-        );
+        const { requiresImage, requiresFile, request: capabilityScopedRequest } = resolveRequiredCapabilities(normalizedRequest);
+        const candidates = router.resolveCandidates(capabilityScopedRequest);
         const startedAt = nowMs(runtime);
         const requestId = resolveEventRequestId(normalizedRequest.logContext);
         const candidateSummaries = candidates.map(summarizeRoute);
@@ -4003,7 +4421,10 @@ function createClient(configOrInput, options = {}) {
         const attempts = [];
         const wideAttempts = [];
         if (candidates.length === 0) {
-          const error = new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
+          const error = requiresImage || requiresFile ? new AiConnectError(
+            "unsupported_capability",
+            `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
+          ) : new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
           await emitWideEvent({
             timestamp: isoTimestamp(startedAt),
             event: "ai_connect.operation",
@@ -4479,12 +4900,32 @@ function trimTrailingSlash(value) {
 function appendPath(baseUrl, suffix) {
   return `${trimTrailingSlash(baseUrl)}/${suffix.replace(/^\/+/, "")}`;
 }
+function isAbortError(error) {
+  if (error instanceof AiConnectError) {
+    return error.code === "aborted";
+  }
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function attachPartsToLastUserTurn(conversation, createEmptyUserTurn) {
+  let targetIndex = -1;
+  for (let index = conversation.length - 1; index >= 0; index -= 1) {
+    if (conversation[index]?.role === "user") {
+      targetIndex = index;
+      break;
+    }
+  }
+  if (targetIndex === -1) {
+    conversation.push(createEmptyUserTurn());
+    targetIndex = conversation.length - 1;
+  }
+  return conversation[targetIndex];
+}
 function resolveOpenAiEndpoint(route, operation) {
   const configured = route.transport.baseUrl?.trim();
   if (!configured) {
     return operation === "image" ? "https://api.openai.com/v1/images/generations" : "https://api.openai.com/v1/chat/completions";
   }
-  if (configured.endsWith("/chat/completions") || configured.endsWith("/images/generations")) {
+  if (operation === "text" && configured.endsWith("/chat/completions") || operation === "image" && configured.endsWith("/images/generations")) {
     return configured;
   }
   return appendPath(
@@ -5315,7 +5756,7 @@ async function uploadAnthropicFile(payload, uploader) {
   }
   try {
     const base = uploader.context.route.transport.baseUrl?.trim();
-    const root = base ? base.replace(/\/(messages|models)$/, "") : "https://api.anthropic.com/v1";
+    const root = base ? trimTrailingSlash(base).replace(/\/(messages|models)$/, "") : "https://api.anthropic.com/v1";
     const endpoint = appendPath(root, "/files");
     const form = new FormData();
     form.append(
@@ -5339,7 +5780,10 @@ async function uploadAnthropicFile(payload, uploader) {
     }
     const id = recordOf(data).id;
     return typeof id === "string" ? id : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5372,7 +5816,10 @@ async function uploadOpenAiFile(payload, uploader) {
     }
     const id = recordOf(data).id;
     return typeof id === "string" ? id : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5382,10 +5829,11 @@ async function uploadGeminiFile(payload, uploader) {
   }
   try {
     const base = uploader.context.route.transport.baseUrl?.trim();
-    const endpoint = base ? appendPath(
-      base.replace(/\/v1beta\/models.*$/, "/v1beta").replace(/\/+$/, ""),
+    const root = base ? trimTrailingSlash(base.replace(/\/v1beta\/models.*$/, "/v1beta")) : void 0;
+    const endpoint = root ? appendPath(
+      root.endsWith("/v1beta") ? `${root.slice(0, -"/v1beta".length)}/upload/v1beta` : `${root}/upload`,
       "/files"
-    ).replace("/v1beta/files", "/upload/v1beta/files") : "https://generativelanguage.googleapis.com/upload/v1beta/files";
+    ) : "https://generativelanguage.googleapis.com/upload/v1beta/files";
     const response = await uploader.fetchImpl(endpoint, {
       method: "POST",
       headers: {
@@ -5404,7 +5852,10 @@ async function uploadGeminiFile(payload, uploader) {
     const file = recordOf(recordOf(data).file);
     const uri = file.uri ?? recordOf(data).uri;
     return typeof uri === "string" ? uri : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5602,21 +6053,10 @@ function attachOpenAiParts(conversation, parts) {
   if (parts.length === 0) {
     return conversation;
   }
-  let targetIndex = -1;
-  for (let index = conversation.length - 1; index >= 0; index -= 1) {
-    if (conversation[index]?.role === "user") {
-      targetIndex = index;
-      break;
-    }
-  }
-  if (targetIndex === -1) {
-    conversation.push({
-      role: "user",
-      content: ""
-    });
-    targetIndex = conversation.length - 1;
-  }
-  const target = conversation[targetIndex];
+  const target = attachPartsToLastUserTurn(conversation, () => ({
+    role: "user",
+    content: ""
+  }));
   const baseParts = typeof target.content === "string" && target.content.trim().length > 0 ? [{ type: "text", text: target.content }] : Array.isArray(target.content) ? target.content : [];
   target.content = [...baseParts, ...parts];
   return conversation;
@@ -5702,21 +6142,10 @@ async function anthropicRequest(messages, attachments, uploader) {
   }
   const attachmentParts = await anthropicAttachmentParts(attachments, uploader);
   if (attachmentParts.length > 0) {
-    let targetIndex = -1;
-    for (let index = conversation.length - 1; index >= 0; index -= 1) {
-      if (conversation[index]?.role === "user") {
-        targetIndex = index;
-        break;
-      }
-    }
-    if (targetIndex === -1) {
-      conversation.push({
-        role: "user",
-        content: ""
-      });
-      targetIndex = conversation.length - 1;
-    }
-    const target = conversation[targetIndex];
+    const target = attachPartsToLastUserTurn(conversation, () => ({
+      role: "user",
+      content: ""
+    }));
     const baseParts = typeof target.content === "string" && target.content.trim().length > 0 ? [{ type: "text", text: target.content }] : Array.isArray(target.content) ? target.content : [];
     target.content = [...baseParts, ...attachmentParts];
   }
@@ -5727,12 +6156,27 @@ async function anthropicRequest(messages, attachments, uploader) {
 }
 async function geminiRequest(messages, attachments, uploader) {
   const system = messages.filter((message) => message.role === "system").map((message) => message.content).join("\n\n");
+  const toolNameByCallId = /* @__PURE__ */ new Map();
+  for (const message of messages) {
+    if (hasAssistantToolCalls(message)) {
+      for (const call of message.toolCalls) {
+        toolNameByCallId.set(call.id, call.name);
+      }
+    }
+  }
   const contents = messages.filter((message) => message.role !== "system").reduce(
     (conversation, message) => {
       if (isToolMessage(message)) {
+        const resolvedName = message.toolName ?? toolNameByCallId.get(message.toolCallId);
+        if (!resolvedName) {
+          throw new AiConnectError(
+            "validation_error",
+            `Gemini functionResponse requires a tool name: the tool message for toolCallId "${message.toolCallId}" has no toolName and no matching assistant toolCall was found.`
+          );
+        }
         const response = {
           functionResponse: {
-            name: message.toolName ?? "tool",
+            name: resolvedName,
             response: isRecord(message.data) ? message.data : {
               content: message.content,
               ...message.isError !== void 0 ? { isError: message.isError } : {}
@@ -5779,21 +6223,11 @@ async function geminiRequest(messages, attachments, uploader) {
   );
   const attachmentParts = await geminiAttachmentParts(attachments, uploader);
   if (attachmentParts.length > 0) {
-    let targetIndex = -1;
-    for (let index = contents.length - 1; index >= 0; index -= 1) {
-      if (contents[index]?.role === "user") {
-        targetIndex = index;
-        break;
-      }
-    }
-    if (targetIndex === -1) {
-      contents.push({
-        role: "user",
-        parts: []
-      });
-      targetIndex = contents.length - 1;
-    }
-    contents[targetIndex].parts.push(...attachmentParts);
+    const target = attachPartsToLastUserTurn(contents, () => ({
+      role: "user",
+      parts: []
+    }));
+    target.parts.push(...attachmentParts);
   }
   return {
     ...system ? {
@@ -5843,6 +6277,22 @@ function extractThoughts(value) {
   const joined = thoughts.join("\n").trim();
   return joined.length > 0 ? joined : void 0;
 }
+function extractThinking(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const thinking = value.flatMap((part) => {
+    if (part && typeof part === "object" && part.type === "thinking") {
+      const candidate = part.thinking;
+      if (typeof candidate === "string") {
+        return [candidate];
+      }
+    }
+    return [];
+  });
+  const joined = thinking.join("\n").trim();
+  return joined.length > 0 ? joined : void 0;
+}
 function imageAttachmentsFromPayload(payload, ...sources) {
   return extractImagePayloads(payload, ...sources).map(
     (item) => preparePortableFile(item)
@@ -5930,6 +6380,10 @@ function buildOpenAiChatBody(context, messages, parameters, responseFormat, opts
     model: context.route.model,
     messages,
     stream: opts.stream,
+    // Ask OpenAI-compatible streaming routes for the trailing usage chunk; without
+    // `stream_options.include_usage` the SSE stream carries no `usage` block and
+    // `runOpenAiStream` would always report `usage: undefined` (H5).
+    ...opts.stream ? { stream_options: { include_usage: true } } : {},
     ...parameters?.maxTokens !== void 0 ? { max_tokens: parameters.maxTokens } : {},
     ...parameters?.temperature !== void 0 ? { temperature: parameters.temperature } : {},
     ...parameters?.topP !== void 0 ? { top_p: parameters.topP } : {},
@@ -6084,6 +6538,11 @@ async function* runOpenAiStream(fetchImpl, context) {
   }
   const response = outcome.response;
   const streamWarnings = [...uploaderWarnings];
+  if (parameters?.candidateCount && parameters.candidateCount > 1) {
+    streamWarnings.push(
+      "candidateCount > 1 is forwarded to OpenAI-compatible text routes, but the normalized result returns only the first choice."
+    );
+  }
   if (droppedResponseFormat) {
     streamWarnings.push(
       "response_format was rejected by the OpenAI-compatible route (HTTP 400); the request was retried once without response_format and structured-output formatting was NOT enforced."
@@ -6229,8 +6688,7 @@ function buildOpenAiStreamResult(context, text, toolCalls, usage, warnings) {
     } : {}
   };
 }
-async function runOpenAiImage(fetchImpl, context) {
-  const apiKey = resolveApiKey(context.route, context.runtime);
+async function runProviderImage(fetchImpl, context, opts) {
   const referenceImages = imageReferenceFiles(context);
   const bundle = buildImagePromptBundle({
     request: context.request,
@@ -6239,10 +6697,10 @@ async function runOpenAiImage(fetchImpl, context) {
   });
   const baseFields = buildImageRequestFields(context, bundle);
   const useEditEndpoint = shouldUseImageEditEndpoint(context);
-  const endpoint = useEditEndpoint ? resolveOpenAiImageEditEndpoint(context.route) : resolveOpenAiEndpoint(context.route, "image");
+  const endpoint = useEditEndpoint ? opts.resolveEditEndpoint(context.route) : opts.resolveEndpoint(context.route);
   transportSummary(
     context,
-    useEditEndpoint ? "openai-image-edit" : "openai-image",
+    useEditEndpoint ? `${opts.providerLabel}-image-edit` : `${opts.providerLabel}-image`,
     endpoint,
     "POST",
     false,
@@ -6255,23 +6713,21 @@ async function runOpenAiImage(fetchImpl, context) {
   );
   const response = await fetchImpl(endpoint, useEditEndpoint ? {
     method: "POST",
-    headers: {
-      authorization: `Bearer ${apiKey}`
-    },
+    headers: { ...opts.authHeaders },
     body: await buildImageEditFormData(context, baseFields),
     signal: context.abort.signal
   } : {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`
+      ...opts.authHeaders
     },
     body: JSON.stringify(baseFields),
     signal: context.abort.signal
   });
   const payload = await readPayload(response);
   if (!response.ok) {
-    throw classifyApiError("openai", response, payload);
+    throw classifyApiError(opts.classifyProvider, response, payload);
   }
   return {
     data: {
@@ -6281,6 +6737,16 @@ async function runOpenAiImage(fetchImpl, context) {
     attachments: imageAttachmentsFromPayload(payload)
   };
 }
+async function runOpenAiImage(fetchImpl, context) {
+  const apiKey = resolveApiKey(context.route, context.runtime);
+  return runProviderImage(fetchImpl, context, {
+    resolveEndpoint: (route) => resolveOpenAiEndpoint(route, "image"),
+    resolveEditEndpoint: (route) => resolveOpenAiImageEditEndpoint(route),
+    authHeaders: { authorization: `Bearer ${apiKey}` },
+    providerLabel: "openai",
+    classifyProvider: "openai"
+  });
+}
 async function runAnthropic(fetchImpl, context) {
   const apiKey = resolveApiKey(context.route, context.runtime);
   const uploaderWarnings = [];
@@ -6292,6 +6758,8 @@ async function runAnthropic(fetchImpl, context) {
   const parameters = context.request.parameters;
   const requestBody = {
     model: context.route.model,
+    // Anthropic REQUIRES `max_tokens` (unlike OpenAI/Gemini, where it is optional), so a
+    // provider-specific default of 4096 is applied when the caller omits `maxTokens`.
     max_tokens: parameters?.maxTokens ?? 4096,
     ...parameters?.temperature !== void 0 ? { temperature: parameters.temperature } : {},
     ...parameters?.topP !== void 0 ? { top_p: parameters.topP } : {},
@@ -6321,8 +6789,12 @@ async function runAnthropic(fetchImpl, context) {
     throw classifyApiError("anthropic", response, payload);
   }
   const data = payload;
+  const anthropicReasoning = extractThinking(data.content);
   return {
     text: extractText(data.content),
+    // Anthropic extended-thinking blocks, separated from the answer (consumers route this
+    // to a thinking UI), mirroring the Gemini `reasoning` path.
+    ...anthropicReasoning ? { reasoning: anthropicReasoning } : {},
     data,
     ...anthropicToolCallsFromPayload(data).length > 0 ? { toolCalls: anthropicToolCallsFromPayload(data) } : {},
     ...uploaderWarnings.length > 0 ? { warnings: uploaderWarnings } : {},
@@ -6410,63 +6882,21 @@ async function runGemini(fetchImpl, context) {
         calls: 1,
         ...data.usageMetadata?.promptTokenCount !== void 0 ? { inputTokens: data.usageMetadata.promptTokenCount } : {},
         ...data.usageMetadata?.candidatesTokenCount !== void 0 ? { outputTokens: data.usageMetadata.candidatesTokenCount } : {},
-        ...data.usageMetadata?.thoughtsTokenCount !== void 0 ? { reasoningTokens: data.usageMetadata.thoughtsTokenCount } : {}
-      }
-    } : {}
-  };
-}
-async function runGeminiImage(fetchImpl, context) {
-  const apiKey = resolveApiKey(context.route, context.runtime);
-  const referenceImages = imageReferenceFiles(context);
-  const bundle = buildImagePromptBundle({
-    request: context.request,
-    model: context.route.model,
-    referenceImages
-  });
-  const baseFields = buildImageRequestFields(context, bundle);
-  const useEditEndpoint = shouldUseImageEditEndpoint(context);
-  const endpoint = useEditEndpoint ? resolveGeminiImageEditEndpoint(context.route) : resolveGeminiImageEndpoint(context.route);
-  transportSummary(
-    context,
-    useEditEndpoint ? "gemini-image-edit" : "gemini-image",
-    endpoint,
-    "POST",
-    false,
-    {
-      ...baseFields,
-      source_image: Boolean(context.request.image?.sourceImage),
-      mask: Boolean(context.request.image?.mask),
-      reference_image_count: referenceImages.length
-    }
-  );
-  const response = await fetchImpl(endpoint, useEditEndpoint ? {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${apiKey}`
-    },
-    body: await buildImageEditFormData(context, baseFields),
-    signal: context.abort.signal
-  } : {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`
-    },
-    body: JSON.stringify(baseFields),
-    signal: context.abort.signal
-  });
-  const payload = await readPayload(response);
-  if (!response.ok) {
-    throw classifyApiError(context.route.provider, response, payload);
-  }
-  return {
-    data: {
-      request: bundle,
-      response: payload
-    },
-    attachments: imageAttachmentsFromPayload(payload)
+        ...data.usageMetadata?.thoughtsTokenCount !== void 0 ? { reasoningTokens: data.usageMetadata.thoughtsTokenCount } : {}
+      }
+    } : {}
   };
 }
+async function runGeminiImage(fetchImpl, context) {
+  const apiKey = resolveApiKey(context.route, context.runtime);
+  return runProviderImage(fetchImpl, context, {
+    resolveEndpoint: (route) => resolveGeminiImageEndpoint(route),
+    resolveEditEndpoint: (route) => resolveGeminiImageEditEndpoint(route),
+    authHeaders: { authorization: `Bearer ${apiKey}` },
+    providerLabel: "gemini",
+    classifyProvider: context.route.provider
+  });
+}
 function verifyApiRoute(route, runtime) {
   resolveApiKey(route, runtime);
   return [];
@@ -6544,9 +6974,12 @@ var AI_CONNECT_DEFAULT_SERVER_PRESETS = {
     transportId: "opencode-server"
   }
 };
-var AI_CONNECT_DEFAULT_SERVER_COMMANDS = {
-  "opencode:opencode-server": AI_CONNECT_DEFAULT_SERVER_PRESETS.opencode.command
-};
+var AI_CONNECT_DEFAULT_SERVER_COMMANDS = Object.fromEntries(
+  Object.values(AI_CONNECT_DEFAULT_SERVER_PRESETS).map((preset) => [
+    `${preset.id}:${preset.transportId}`,
+    preset.command
+  ])
+);
 
 // src/catalog.ts
 var TEXT_PROVIDER_CATALOG = [
@@ -6763,8 +7196,119 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+
+// src/transport-runtime.ts
+var MINIMAL_ENV_KEYS = [
+  "PATH",
+  "HOME",
+  "USERPROFILE",
+  "HTTPS_PROXY",
+  "HTTP_PROXY",
+  "NO_PROXY",
+  "https_proxy",
+  "http_proxy",
+  "no_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "SystemRoot",
+  "windir",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "TEMP",
+  "TMP",
+  "PATHEXT",
+  "ComSpec",
+  "NUMBER_OF_PROCESSORS"
+];
+function resolveChildEnv(opts = {}) {
+  const extra = opts.extra ?? {};
+  if (opts.envMode === "inherit") {
+    const inherited = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (typeof value === "string") {
+        inherited[key] = value;
+      }
+    }
+    return { ...inherited, ...extra };
+  }
+  const minimal = {};
+  const keys = /* @__PURE__ */ new Set([...MINIMAL_ENV_KEYS, ...opts.allowlist ?? []]);
+  for (const key of keys) {
+    const value = process.env[key];
+    if (typeof value === "string") {
+      minimal[key] = value;
+    }
+  }
+  return { ...minimal, ...extra };
+}
+function killProcessTree(child, signal, detached) {
+  if (process.platform !== "win32" && detached && typeof child.pid === "number") {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
+function resolveManagedCommand(key, optionsCommands, routeCommand, presetCommand) {
+  const resolved = optionsCommands?.[key]?.trim() || routeCommand?.trim() || presetCommand?.trim();
+  if (!resolved) {
+    throw new AiConnectError(
+      "validation_error",
+      `No managed command is configured for "${key}".`
+    );
+  }
+  return resolved;
+}
+var trackedChildren = /* @__PURE__ */ new Set();
+var exitHookRegistered = false;
+function killAllTrackedChildren() {
+  for (const tracked of trackedChildren) {
+    killProcessTree(tracked.child, "SIGKILL", tracked.detached);
+  }
+  trackedChildren.clear();
+}
+function ensureExitHook() {
+  if (exitHookRegistered) {
+    return;
+  }
+  exitHookRegistered = true;
+  process.on("exit", () => {
+    killAllTrackedChildren();
+  });
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    const handler = () => {
+      killAllTrackedChildren();
+      process.removeListener(signal, handler);
+      if (process.listenerCount(signal) === 0) {
+        process.kill(process.pid, signal);
+      }
+    };
+    process.on(signal, handler);
+  }
+}
+function trackChild(child, detached) {
+  ensureExitHook();
+  const entry = { child, detached };
+  trackedChildren.add(entry);
+  const untrack = () => {
+    trackedChildren.delete(entry);
+  };
+  child.once("close", untrack);
+  child.once("exit", untrack);
+  return untrack;
+}
+
+// src/acp.ts
 var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_SESSION_CACHE_IDLE_TTL_MS = 6e4;
+var MAX_ACP_STDERR_CHARS = 64 * 1024;
+var MAX_ACP_STREAM_QUEUE = 1024;
 var IMAGE_EXTENSIONS = /* @__PURE__ */ new Map([
   [".png", "image/png"],
   [".jpg", "image/jpeg"],
@@ -6797,6 +7341,20 @@ var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
 function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+var ACP_HARNESS_NOISE_PATTERNS = [
+  /^модель переключена на .+?\.?(?:\s*готов к работе[.!…]*)?$/iu,
+  /^готов к работе[.!…]*$/iu,
+  /^жду (?:вашего вопроса|вопроса или задачи|вашей задачи|вашего ответа|явного запроса)[^]*$/iu,
+  /^это сообщение помечено как локальная команда[^]*$/iu,
+  /^<local-command-(?:caveat|stdout|name|message|args)[^>]*>[^]*$/iu
+];
+function isHarnessNoiseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+  return ACP_HARNESS_NOISE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
 function splitCommandLine(commandLine) {
   const matches = commandLine.match(/"[^"]*"|'[^']*'|[^\s]+/g) ?? [];
   const parts = matches.map((part) => {
@@ -7039,24 +7597,29 @@ function prepareClaudeLaunchRuntime(base, launch) {
     launch
   };
 }
+var ACP_LAUNCH_PREPARERS = {
+  "opencode-acp": prepareOpenCodeLaunchRuntime,
+  "codex-acp": prepareCodexLaunchRuntime,
+  "claude-code-acp": prepareClaudeLaunchRuntime
+};
 async function prepareAcpLaunchRuntime(route, options, commandLine, cwdOverride) {
   const launch = normalizeLaunchOptions(route, options);
   const base = {
     commandLine,
     cwd: path.resolve(cwdOverride ?? options?.cwd ?? process.cwd()),
-    env: {
-      ...process.env,
-      ...options?.env ?? {}
-    }
+    // SYS-2: minimal env by default — do NOT hand the host's full process.env
+    // (other-provider keys, CI tokens) to third-party ACP agents. Extra env is
+    // layered via options.env.
+    env: resolveChildEnv({ extra: options?.env ?? {} })
   };
-  if (route.transport.id === "opencode-acp") {
-    return prepareOpenCodeLaunchRuntime(base, launch);
-  }
-  if (route.transport.id === "codex-acp") {
-    return prepareCodexLaunchRuntime(base, launch);
+  const preparer = ACP_LAUNCH_PREPARERS[route.transport.id];
+  if (preparer) {
+    return await preparer(base, launch);
   }
-  if (route.transport.id === "claude-code-acp") {
-    return prepareClaudeLaunchRuntime(base, launch);
+  if (launch.contextMode !== "workspace" || launch.skillsMode !== "default") {
+    console.warn(
+      `[ai-connect] ACP transport "${route.transport.id}" has no launch-runtime preparer; requested contextMode/skillsMode isolation is not applied.`
+    );
   }
   return {
     ...base,
@@ -7088,8 +7651,27 @@ function mimeTypeFromPath(filePath) {
 function isTextPath(filePath) {
   return TEXT_EXTENSIONS2.has(path.extname(filePath).toLowerCase());
 }
-function isWithinRoot(rootDir, targetPath) {
-  const relative = path.relative(rootDir, targetPath);
+async function resolveRealPathTolerant(target) {
+  try {
+    return await fs.realpath(target);
+  } catch {
+    const parent = path.dirname(target);
+    if (parent === target) {
+      return target;
+    }
+    const realParent = await resolveRealPathTolerant(parent);
+    return path.join(realParent, path.basename(target));
+  }
+}
+async function isWithinRoot(rootDir, targetPath) {
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(rootDir);
+  } catch {
+    realRoot = path.resolve(rootDir);
+  }
+  const realTarget = await resolveRealPathTolerant(path.resolve(targetPath));
+  const relative = path.relative(realRoot, realTarget);
   return relative.length === 0 || !relative.startsWith("..") && !path.isAbsolute(relative);
 }
 function buildMessageTranscript(context) {
@@ -7516,46 +8098,58 @@ function extractTextChunk(update) {
   }
   return typeof content.text === "string" && content.text.length > 0 ? content.text : void 0;
 }
+function isAuthErrorMessage(message) {
+  return /unauthor|authentication|invalid[_\s-]?(api[_\s-]?key|credential|token)|forbidden|\b40[13]\b/i.test(
+    message
+  );
+}
 function normalizeAcpError(error) {
   if (error instanceof AiConnectError) {
     return error;
   }
+  if (error instanceof Error) {
+    const message = error.message || "ACP transport failed.";
+    const errno = error.code;
+    if (errno === "ENOENT" || errno === "EACCES" || errno === "ENOEXEC" || message.toLowerCase().includes("timed out")) {
+      return new AiConnectError("local_harness_unavailable", message);
+    }
+    if (isAuthErrorMessage(message)) {
+      return new AiConnectError("auth_error", message);
+    }
+    return new AiConnectError("temporary_unavailable", message);
+  }
   if (isRecord2(error)) {
     const code = typeof error.code === "number" ? error.code : void 0;
     const message = typeof error.message === "string" ? error.message : "ACP transport failed.";
     if (code === -32601 || code === -32602) {
       return new AiConnectError("not_supported", message);
     }
-    if (message.toLowerCase().includes("auth")) {
+    if (isAuthErrorMessage(message)) {
       return new AiConnectError("auth_error", message);
     }
     return new AiConnectError("temporary_unavailable", message);
   }
-  if (error instanceof Error) {
-    const message = error.message;
-    if ("code" in error && error.code === "ENOENT") {
-      return new AiConnectError("local_harness_unavailable", message);
-    }
-    if (message.toLowerCase().includes("timed out")) {
-      return new AiConnectError("local_harness_unavailable", message);
-    }
-    return new AiConnectError("temporary_unavailable", message);
-  }
   return new AiConnectError(
     "temporary_unavailable",
     "ACP transport failed."
   );
 }
 function resolveAcpCommand(route, options) {
-  const override = options?.commands?.[`${route.provider}:${route.transport.id}`] ?? options?.commands?.[route.transport.id] ?? options?.commands?.[route.provider];
-  const resolved = override ?? route.transport.command ?? AI_CONNECT_DEFAULT_ACP_COMMANDS[`${route.provider}:${route.transport.id}`];
-  if (!resolved) {
+  const key = `${route.provider}:${route.transport.id}`;
+  const optionsOverride = options?.commands?.[key] ?? options?.commands?.[route.transport.id] ?? options?.commands?.[route.provider];
+  try {
+    return resolveManagedCommand(
+      key,
+      optionsOverride ? { [key]: optionsOverride } : void 0,
+      route.transport.command,
+      AI_CONNECT_DEFAULT_ACP_COMMANDS[key]
+    );
+  } catch {
     throw new AiConnectError(
       "validation_error",
       `No ACP command is configured for route "${route.id}".`
     );
   }
-  return resolved;
 }
 function resolveAcpExecutable(route, options) {
   return splitCommandLine(resolveAcpCommand(route, options)).command;
@@ -7633,6 +8227,7 @@ function buildAcpLifecycle(route, authRequest, mode) {
   }
   steps.push("session/new");
   if (mode === "prompt") {
+    steps.push("session/set_model");
     steps.push("session/prompt");
   }
   return { steps, keys };
@@ -7705,14 +8300,7 @@ async function settleClosePromise(closePromise, timeoutMs = 1500) {
   ]);
 }
 function killAcpProcess(child, signal) {
-  if (process.platform !== "win32" && typeof child.pid === "number") {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-    }
-  }
-  child.kill(signal);
+  killProcessTree(child, signal, process.platform !== "win32");
 }
 var AcpConnection = class {
   commandLine;
@@ -7720,6 +8308,9 @@ var AcpConnection = class {
   env;
   timeoutMs;
   permissionMode;
+  selectModel;
+  suppressHarnessNoise;
+  failOnHarnessOnlyTurn;
   command;
   args;
   child;
@@ -7741,6 +8332,9 @@ var AcpConnection = class {
     this.env = options.env;
     this.timeoutMs = options.timeoutMs;
     this.permissionMode = options.permissionMode;
+    this.selectModel = options.selectModel;
+    this.suppressHarnessNoise = options.suppressHarnessNoise;
+    this.failOnHarnessOnlyTurn = options.failOnHarnessOnlyTurn;
     const resolved = splitCommandLine(options.commandLine);
     this.command = resolved.command;
     this.args = resolved.args;
@@ -7773,8 +8367,18 @@ var AcpConnection = class {
         usage: void 0,
         attachments: [],
         warnings: [],
+        suppressNoise: this.suppressHarnessNoise,
+        lineBuffer: "",
+        harnessMarkers: [],
         ...onDelta ? { onDelta } : {}
       };
+      await this.selectSessionModel(
+        sessionId,
+        context.route,
+        session,
+        transport.phases ?? [],
+        this.activePrompt.warnings
+      );
       let stopReason;
       const abortSignal = context.abort.signal;
       let abortListener;
@@ -7817,13 +8421,30 @@ var AcpConnection = class {
         }
         this.bumpIdleTimer();
       }
+      this.flushHarnessLineBuffer();
       const stderrSlice = this.stderr.slice(stderrOffset).trim();
       const warnings = [...this.activePrompt.warnings];
+      if (this.activePrompt.harnessMarkers.length > 0) {
+        warnings.push(
+          `ACP: filtered ${this.activePrompt.harnessMarkers.length} interactive-harness line(s) from the response.`
+        );
+      }
       if (stderrSlice.length > 0) {
         warnings.push(stderrSlice);
       }
+      if (this.stderr.length > MAX_ACP_STDERR_CHARS) {
+        this.stderr = this.stderr.slice(-MAX_ACP_STDERR_CHARS);
+      }
+      const text = this.activePrompt.text.trim();
+      if (this.failOnHarnessOnlyTurn && this.activePrompt.harnessMarkers.length > 0 && text.length === 0) {
+        this.activePrompt = void 0;
+        throw new AiConnectError(
+          "temporary_unavailable",
+          "ACP turn returned only interactive-harness output (no task output)."
+        );
+      }
       const result = {
-        text: this.activePrompt.text.trim(),
+        text,
         attachments: [...this.activePrompt.attachments],
         warnings,
         ...this.activePrompt.usage ? { usage: this.activePrompt.usage } : {},
@@ -7983,6 +8604,12 @@ var AcpConnection = class {
       this.stderr = "";
       this.pending.clear();
       this.messageQueue = Promise.resolve();
+      child.stdin?.on("error", (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        this.stderr += `[ai-connect] ACP stdin error: ${message}
+`;
+      });
+      trackChild(child, process.platform !== "win32");
       child.stdout.setEncoding("utf8");
       child.stdout.on("data", (chunk) => {
         this.buffer += chunk;
@@ -8046,8 +8673,14 @@ var AcpConnection = class {
     if (!stdin) {
       return;
     }
-    stdin.write(`${JSON.stringify(message)}
+    try {
+      stdin.write(`${JSON.stringify(message)}
 `);
+    } catch (error) {
+      const messageText = error instanceof Error ? error.message : String(error);
+      this.stderr += `[ai-connect] ACP stdin write error (reply): ${messageText}
+`;
+    }
   }
   failPending(error) {
     for (const entry of this.pending.values()) {
@@ -8068,7 +8701,7 @@ var AcpConnection = class {
     }
     if (message.method === "readTextFile") {
       const filePath = typeof params.path === "string" ? path.resolve(params.path) : void 0;
-      if (!filePath || !isWithinRoot(this.cwd, filePath)) {
+      if (!filePath || !await isWithinRoot(this.cwd, filePath)) {
         this.reply({
           jsonrpc: "2.0",
           id: message.id,
@@ -8101,7 +8734,7 @@ var AcpConnection = class {
       }
       const filePath = typeof params.path === "string" ? path.resolve(params.path) : void 0;
       const content = typeof params.content === "string" ? params.content : void 0;
-      if (!filePath || content === void 0 || !isWithinRoot(this.cwd, filePath)) {
+      if (!filePath || content === void 0 || !await isWithinRoot(this.cwd, filePath)) {
         this.reply({
           jsonrpc: "2.0",
           id: message.id,
@@ -8130,6 +8763,108 @@ var AcpConnection = class {
       }
     });
   }
+  /**
+   * Select the route's model through the ACP protocol (TASK-033 / UR-002).
+   * Best-effort matrix: skip when disabled / no model / no advertised catalog /
+   * already current; warn (not silently default) when the requested model is not
+   * in the agent's `availableModels`; otherwise `session/set_model` and surface
+   * any error as a warning. Never throws — a failed protocol selection must not
+   * fail the generation.
+   */
+  async selectSessionModel(sessionId, route, sessionResult, phases, warnings) {
+    if (!this.selectModel) {
+      return;
+    }
+    const desiredModel = route.model?.trim();
+    if (!desiredModel) {
+      return;
+    }
+    const catalog = modelCatalogFromSession(sessionResult);
+    if (!catalog) {
+      return;
+    }
+    if (catalog.currentModelId === desiredModel) {
+      return;
+    }
+    const available = catalog.availableModels ?? [];
+    if (available.length > 0 && !available.some((entry) => entry.modelId === desiredModel)) {
+      warnings.push(
+        `ACP agent's available models [${available.map((entry) => entry.modelId).join(", ")}] do not include route model "${desiredModel}"; model not switched via protocol.`
+      );
+      return;
+    }
+    try {
+      await measurePhase(
+        phases,
+        "session/set_model",
+        async () => this.request("session/set_model", {
+          sessionId,
+          modelId: desiredModel
+        })
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : isRecord2(error) && typeof error.message === "string" ? error.message : String(error);
+      warnings.push(
+        `ACP session/set_model("${desiredModel}") failed: ${message}`
+      );
+    }
+  }
+  /**
+   * Append `agent_message_chunk` text (TASK-033 / UR-003). With suppression off
+   * (legacy) the chunk streams + accumulates raw. With suppression on, the chunk
+   * is line-buffered: each COMPLETE line is classified and either dropped (a
+   * harness marker — no delta, no accumulation) or emitted; the trailing partial
+   * line waits in `lineBuffer` for the next chunk or the end-of-turn flush.
+   */
+  appendAgentText(chunk) {
+    const state = this.activePrompt;
+    if (!state) {
+      return;
+    }
+    if (!state.suppressNoise) {
+      state.onDelta?.(chunk);
+      state.text += chunk;
+      return;
+    }
+    state.lineBuffer += chunk;
+    let newlineIndex = state.lineBuffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = state.lineBuffer.slice(0, newlineIndex + 1);
+      state.lineBuffer = state.lineBuffer.slice(newlineIndex + 1);
+      this.emitAgentLine(line);
+      newlineIndex = state.lineBuffer.indexOf("\n");
+    }
+  }
+  /** Flush any trailing partial line through the harness-noise classifier. */
+  flushHarnessLineBuffer() {
+    const state = this.activePrompt;
+    if (!state || !state.suppressNoise) {
+      return;
+    }
+    const remaining = state.lineBuffer;
+    state.lineBuffer = "";
+    if (remaining.length > 0) {
+      this.emitAgentLine(remaining);
+    }
+  }
+  /**
+   * Emit one classified line: a curated harness marker is recorded + dropped
+   * (no delta, no accumulation); any other line streams + accumulates. `line`
+   * may carry a trailing newline — classification runs on the content.
+   */
+  emitAgentLine(line) {
+    const state = this.activePrompt;
+    if (!state) {
+      return;
+    }
+    const content = line.endsWith("\n") ? line.slice(0, -1) : line;
+    if (isHarnessNoiseLine(content)) {
+      state.harnessMarkers.push(content.trim());
+      return;
+    }
+    state.onDelta?.(line);
+    state.text += line;
+  }
   handleNotification(message) {
     if (message.method !== "session/update" || !this.activePrompt) {
       return;
@@ -8144,8 +8879,7 @@ var AcpConnection = class {
     }
     const chunk = extractTextChunk(update);
     if (update.sessionUpdate === "agent_message_chunk" && chunk) {
-      this.activePrompt.onDelta?.(chunk);
-      this.activePrompt.text += chunk;
+      this.appendAgentText(chunk);
     }
     if (update.sessionUpdate === "agent_thought_chunk" && chunk) {
       this.activePrompt.warnings.push(chunk);
@@ -8274,8 +9008,20 @@ var AcpConnection = class {
         );
         return;
       }
-      stdin.write(`${JSON.stringify(payload)}
+      try {
+        stdin.write(`${JSON.stringify(payload)}
 `);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        const messageText = error instanceof Error ? error.message : String(error);
+        reject(
+          new AiConnectError(
+            "local_harness_unavailable",
+            `ACP command "${this.commandLine}" stdin write failed: ${messageText}`
+          )
+        );
+      }
     });
   }
 };
@@ -8332,7 +9078,10 @@ function createAcpTransportManager(options) {
       cwd: runtime.cwd,
       env: runtime.env,
       timeoutMs: promptTimeout(options),
-      permissionMode: options?.permissionMode ?? "deny-all"
+      permissionMode: options?.permissionMode ?? "deny-all",
+      selectModel: options?.selectModel ?? true,
+      suppressHarnessNoise: options?.suppressHarnessNoise ?? true,
+      failOnHarnessOnlyTurn: options?.failOnHarnessOnlyTurn ?? true
     };
   }
   function getPool(key) {
@@ -8543,6 +9292,10 @@ function createAcpTransportManager(options) {
       let notify;
       const onDelta = (text) => {
         deltas.push(text);
+        if (deltas.length > MAX_ACP_STREAM_QUEUE) {
+          const overflow = deltas.splice(0, deltas.length - MAX_ACP_STREAM_QUEUE);
+          deltas.unshift(overflow.join(""));
+        }
         notify?.();
       };
       let settled = false;
@@ -8680,44 +9433,29 @@ ${message.content}`;
   }).join("\n\n");
 }
 function resolveCliCommand(route, options) {
-  if (route.transport.command?.trim()) {
-    return route.transport.command.trim();
-  }
-  const candidates = [
-    `${route.provider}:${route.transport.id}`,
-    route.transport.id,
-    route.provider
-  ];
-  for (const candidate of candidates) {
-    const override = options?.commands?.[candidate]?.trim();
-    if (override) {
-      return override;
-    }
-  }
+  const key = `${route.provider}:${route.transport.id}`;
+  const optionsOverride = options?.commands?.[key]?.trim() || options?.commands?.[route.transport.id]?.trim() || options?.commands?.[route.provider]?.trim() || void 0;
   const presetId = route.transport.cli?.preset ?? defaultCliPresetIdForRoute(route);
-  if (presetId) {
-    const presetCommand = getCliTransportPreset(presetId).command.trim();
-    if (presetCommand) {
-      return presetCommand;
-    }
-  }
-  const preset = AI_CONNECT_DEFAULT_CLI_COMMANDS[`${route.provider}:${route.transport.id}`];
-  if (preset) {
-    return preset;
+  const presetCommand = (presetId ? getCliTransportPreset(presetId).command.trim() : "") || AI_CONNECT_DEFAULT_CLI_COMMANDS[key] || void 0;
+  try {
+    return resolveManagedCommand(
+      key,
+      optionsOverride ? { [key]: optionsOverride } : void 0,
+      route.transport.command,
+      presetCommand
+    );
+  } catch {
+    throw new AiConnectError(
+      "validation_error",
+      `No CLI command preset is registered for route "${route.id}". Provide transport.command or cli.commands.`
+    );
   }
-  throw new AiConnectError(
-    "validation_error",
-    `No CLI command preset is registered for route "${route.id}". Provide transport.command or cli.commands.`
-  );
 }
 function resolveCliExecutable(route, options) {
   return splitCommandLine2(resolveCliCommand(route, options)).command;
 }
 function buildCliEnvironment(options) {
-  return {
-    ...process.env,
-    ...options?.env ?? {}
-  };
+  return resolveChildEnv({ extra: options?.env ?? {} });
 }
 function buildCliCwd(context, options) {
   return path2.resolve(
@@ -8818,9 +9556,13 @@ function resolveCliTransportOptions(route) {
   } : void 0;
   const merged = {
     ...preset?.options ?? {},
+    // `...route.transport.cli` already spreads argsTemplate + parser (when set on
+    // the route) over the preset defaults, so the previously-present conditional
+    // re-spreads of those two fields were dead/redundant (they re-assigned the
+    // identical value) and have been dropped. fileInput/preset below are NOT
+    // redundant: fileInput is a per-field DEEP merge (mergedFileInput) and preset
+    // is derived (route.transport.cli.preset ?? default), not a plain passthrough.
     ...route.transport.cli ?? {},
-    ...route.transport.cli?.argsTemplate ? { argsTemplate: route.transport.cli.argsTemplate } : {},
-    ...route.transport.cli?.parser ? { parser: route.transport.cli.parser } : {},
     ...mergedFileInput ? { fileInput: mergedFileInput } : {},
     ...presetId ? { preset: presetId } : {}
   };
@@ -8917,7 +9659,7 @@ function materializeTemplateArg(templateArg, values, parameterKeys) {
       }
       return values.outputFile;
     default:
-      if (templateArg.startsWith("--")) {
+      if (templateArg.startsWith("--") && templateArg.length > 2) {
         parameterKeys.push(templateArg);
       }
       return templateArg;
@@ -9070,8 +9812,19 @@ function getValueByPath(value, dotPath) {
   }
   return current;
 }
-function splitJsonlLines(stdout) {
-  return stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
+function parseCliJson(raw, context) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new AiConnectError(
+      "temporary_unavailable",
+      `${context} produced output that is not valid JSON (${detail}).`
+    );
+  }
+}
+function splitJsonlLines(stdout, context = "CLI jsonl parser") {
+  return stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => parseCliJson(line, context));
 }
 function normalizeErrorMessage(value) {
   if (typeof value === "string" && value.trim()) {
@@ -9097,8 +9850,8 @@ function findJsonlSelection(entries, selector) {
   }
   return void 0;
 }
-function parseGenericJsonCli(stdout, parser) {
-  const payload = JSON.parse(stdout);
+function parseGenericJsonCli(stdout, parser, context) {
+  const payload = parseCliJson(stdout, context);
   const errorValue = parser.errorPath ? getValueByPath(payload, parser.errorPath) : void 0;
   const errorMessage = normalizeErrorMessage(errorValue);
   if (errorMessage) {
@@ -9119,8 +9872,8 @@ function parseGenericJsonCli(stdout, parser) {
     data: payload
   };
 }
-function parseGenericJsonlCli(stdout, parser) {
-  const entries = splitJsonlLines(stdout);
+function parseGenericJsonlCli(stdout, parser, context) {
+  const entries = splitJsonlLines(stdout, context);
   const errorValue = parser.error ? findJsonlSelection(entries, parser.error) : void 0;
   const errorMessage = normalizeErrorMessage(errorValue);
   if (errorMessage) {
@@ -9194,7 +9947,7 @@ function parseCliModelList(stdout, parser, selector) {
     );
   }
   const records = parser.kind === "jsonl" ? splitJsonlLines(stdout) : (() => {
-    const payload = JSON.parse(stdout);
+    const payload = parseCliJson(stdout, "CLI discovery json parser");
     const arr = selector.path ? getValueByPath(payload, selector.path) : payload;
     return Array.isArray(arr) ? arr : [];
   })();
@@ -9207,8 +9960,8 @@ function parseCliModelList(stdout, parser, selector) {
   }
   return models;
 }
-function parseClaudeCli(stdout) {
-  const payload = JSON.parse(stdout);
+function parseClaudeCli(stdout, context) {
+  const payload = parseCliJson(stdout, context);
   const text = typeof payload.result === "string" ? payload.result : typeof payload.response === "string" ? payload.response : typeof payload.text === "string" ? payload.text : void 0;
   if (!text) {
     throw new AiConnectError(
@@ -9223,8 +9976,8 @@ function parseClaudeCli(stdout) {
     data: payload
   };
 }
-function parseCodexCli(stdout, outputFileContent) {
-  const events = splitJsonlLines(stdout);
+function parseCodexCli(stdout, outputFileContent, context) {
+  const events = splitJsonlLines(stdout, context);
   let text = outputFileContent?.trim() || void 0;
   let usage;
   for (const event of events) {
@@ -9274,6 +10027,7 @@ function parseCliResult(route, result, outputFileContent) {
     );
   }
   const cliOptions = resolveCliTransportOptions(route);
+  const parseContext = `CLI transport "${route.transport.id}"${cliOptions.preset ? ` (preset ${cliOptions.preset})` : ""}`;
   if (route.transport.cli?.parser) {
     const parser = cliOptions.parser;
     if (!parser) {
@@ -9286,9 +10040,9 @@ function parseCliResult(route, result, outputFileContent) {
       case "text":
         return parseTextCli(result.stdout, parser);
       case "json":
-        return parseGenericJsonCli(stdout, parser);
+        return parseGenericJsonCli(stdout, parser, parseContext);
       default:
-        return parseGenericJsonlCli(stdout, parser);
+        return parseGenericJsonlCli(stdout, parser, parseContext);
     }
   }
   switch (cliOptions.preset) {
@@ -9296,9 +10050,9 @@ function parseCliResult(route, result, outputFileContent) {
       return parseTextCli(stdout, { kind: "text" });
     case "claude":
     case "openclaude":
-      return parseClaudeCli(stdout);
+      return parseClaudeCli(stdout, parseContext);
     case "codex":
-      return parseCodexCli(stdout, outputFileContent);
+      return parseCodexCli(stdout, outputFileContent, parseContext);
     default:
       throw new AiConnectError(
         "not_supported",
@@ -9312,29 +10066,27 @@ function capturePhase(phases, name, startedAt) {
     durationMs: Date.now() - startedAt
   });
 }
+var MAX_CLI_OUTPUT_CHARS = 64 * 1024 * 1024;
 async function executeCliInvocation(invocation, timeoutMs, phases, signal) {
   const spawnStartedAt = Date.now();
+  const detached = process.platform !== "win32";
   const child = spawn2(invocation.command, invocation.args, {
     cwd: invocation.cwd,
     env: invocation.env,
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    detached
   });
   capturePhase(phases, "spawn", spawnStartedAt);
   let stdout = "";
   let stderr = "";
   child.stdout.setEncoding("utf8");
-  child.stdout.on("data", (chunk) => {
-    stdout += chunk;
-  });
   child.stderr.setEncoding("utf8");
-  child.stderr.on("data", (chunk) => {
-    stderr += chunk;
-  });
   const executeStartedAt = Date.now();
   return await new Promise((resolve, reject) => {
     let abortListener;
+    let overflowed = false;
     const timer = setTimeout(() => {
-      child.kill("SIGKILL");
+      killProcessTree(child, "SIGKILL", detached);
       reject(
         new AiConnectError(
           "temporary_unavailable",
@@ -9349,15 +10101,43 @@ async function executeCliInvocation(invocation, timeoutMs, phases, signal) {
         abortListener = void 0;
       }
     };
+    const enforceBufferCap = () => {
+      if (overflowed || stdout.length + stderr.length <= MAX_CLI_OUTPUT_CHARS) {
+        return;
+      }
+      overflowed = true;
+      killProcessTree(child, "SIGKILL", detached);
+      cleanup();
+      reject(
+        new AiConnectError(
+          "temporary_unavailable",
+          `CLI transport "${quoteArg(invocation.command)}" exceeded the ${MAX_CLI_OUTPUT_CHARS}-character output cap.`
+        )
+      );
+    };
+    child.stdout.on("data", (chunk) => {
+      if (overflowed) {
+        return;
+      }
+      stdout += chunk;
+      enforceBufferCap();
+    });
+    child.stderr.on("data", (chunk) => {
+      if (overflowed) {
+        return;
+      }
+      stderr += chunk;
+      enforceBufferCap();
+    });
     if (signal) {
       if (signal.aborted) {
-        child.kill("SIGKILL");
+        killProcessTree(child, "SIGKILL", detached);
         cleanup();
         reject(new AiConnectError("aborted", "CLI transport aborted before execution."));
         return;
       }
       abortListener = () => {
-        child.kill("SIGKILL");
+        killProcessTree(child, "SIGKILL", detached);
         cleanup();
         reject(new AiConnectError("aborted", "CLI transport aborted."));
       };
@@ -9373,6 +10153,9 @@ async function executeCliInvocation(invocation, timeoutMs, phases, signal) {
       );
     });
     child.once("close", (exitCode) => {
+      if (overflowed) {
+        return;
+      }
       cleanup();
       capturePhase(phases, "execute", executeStartedAt);
       resolve({
@@ -9476,7 +10259,10 @@ function createCliTransportManager(options) {
           )
         );
       } finally {
-        await cleanupCliInvocation(invocation);
+        try {
+          await cleanupCliInvocation(invocation);
+        } catch {
+        }
       }
     },
     async runPrompt(context) {
@@ -9516,7 +10302,10 @@ function createCliTransportManager(options) {
         }
         return result;
       } finally {
-        await cleanupCliInvocation(invocation);
+        try {
+          await cleanupCliInvocation(invocation);
+        } catch {
+        }
       }
     }
   };
@@ -9543,28 +10332,21 @@ function splitCommandLine3(commandLine) {
   };
 }
 function resolveServerCommand(route, options) {
-  if (route.transport.command?.trim()) {
-    return route.transport.command.trim();
-  }
-  const candidates = [
-    `${route.provider}:${route.transport.id}`,
-    route.transport.id,
-    route.provider
-  ];
-  for (const candidate of candidates) {
-    const override = options?.commands?.[candidate]?.trim();
-    if (override) {
-      return override;
-    }
-  }
-  const preset = AI_CONNECT_DEFAULT_SERVER_COMMANDS[`${route.provider}:${route.transport.id}`];
-  if (preset) {
-    return preset;
+  const key = `${route.provider}:${route.transport.id}`;
+  const optionsOverride = options?.commands?.[key]?.trim() || options?.commands?.[route.transport.id]?.trim() || options?.commands?.[route.provider]?.trim() || void 0;
+  try {
+    return resolveManagedCommand(
+      key,
+      optionsOverride ? { [key]: optionsOverride } : void 0,
+      route.transport.command,
+      AI_CONNECT_DEFAULT_SERVER_COMMANDS[key]
+    );
+  } catch {
+    throw new AiConnectError(
+      "validation_error",
+      `No server command preset is registered for route "${route.id}". Provide transport.command or server.commands.`
+    );
   }
-  throw new AiConnectError(
-    "validation_error",
-    `No server command preset is registered for route "${route.id}". Provide transport.command or server.commands.`
-  );
 }
 function resolveServerExecutable(route, options) {
   return splitCommandLine3(resolveServerCommand(route, options)).command;
@@ -9636,9 +10418,12 @@ async function findAvailablePort(host = "127.0.0.1") {
 async function waitForServerHealth(fetchLike, origin, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let lastError;
+  const perAttemptTimeoutMs = Math.min(2e3, Math.max(250, timeoutMs));
   while (Date.now() < deadline) {
     try {
-      const response = await fetchLike(joinUrl(origin, "/global/health"));
+      const response = await fetchLike(joinUrl(origin, "/global/health"), {
+        signal: AbortSignal.timeout(perAttemptTimeoutMs)
+      });
       if (response.ok) {
         return;
       }
@@ -9668,14 +10453,14 @@ async function spawnServerInstance(route, options, phases, cwdOverride) {
   }
   args.push("--hostname", host, "--port", String(port));
   const spawnStartedAt = Date.now();
+  const detached = process.platform !== "win32";
   const child = spawn3(resolved.command, args, {
     cwd: cwdOverride ?? options?.cwd ?? process.cwd(),
-    env: {
-      ...process.env,
-      ...options?.env ?? {}
-    },
-    stdio: ["ignore", "pipe", "pipe"]
+    env: resolveChildEnv({ extra: options?.env ?? {} }),
+    stdio: ["ignore", "pipe", "pipe"],
+    detached
   });
+  const untrack = trackChild(child, detached);
   let stderr = "";
   child.stderr.setEncoding("utf8");
   child.stderr.on("data", (chunk) => {
@@ -9691,7 +10476,8 @@ async function spawnServerInstance(route, options, phases, cwdOverride) {
     );
     capturePhase2(phases, "health", healthStartedAt);
   } catch (error) {
-    child.kill("SIGKILL");
+    untrack();
+    killProcessTree(child, "SIGKILL", detached);
     throw new AiConnectError(
       "local_harness_unavailable",
       stderr.trim() || (error instanceof Error ? error.message : "Failed to start local server transport.")
@@ -9699,15 +10485,17 @@ async function spawnServerInstance(route, options, phases, cwdOverride) {
   }
   return {
     origin,
+    child,
     dispose: async () => {
+      untrack();
       if (child.killed) {
         return;
       }
-      child.kill("SIGTERM");
+      killProcessTree(child, "SIGTERM", detached);
       await new Promise((resolve) => {
         child.once("close", () => resolve());
         setTimeout(() => {
-          child.kill("SIGKILL");
+          killProcessTree(child, "SIGKILL", detached);
           resolve();
         }, 1e3).unref?.();
       });
@@ -9807,7 +10595,17 @@ function createServerTransportManager(options) {
     const pending = spawnServerInstance(route, options, phases, cwdOverride);
     instances.set(key, pending);
     try {
-      return await pending;
+      const instance = await pending;
+      if (instance.child) {
+        const evict = () => {
+          if (instances.get(key) === pending) {
+            instances.delete(key);
+          }
+        };
+        instance.child.once("exit", evict);
+        instance.child.once("error", evict);
+      }
+      return instance;
     } catch (error) {
       instances.delete(key);
       throw error;
@@ -9837,7 +10635,10 @@ function createServerTransportManager(options) {
         headers: {
           "content-type": "application/json"
         },
-        body: JSON.stringify({})
+        body: JSON.stringify({}),
+        // H6: honor caller cancel / operation timeout on session creation too
+        // (was only wired on the message fetch).
+        signal: context.abort.signal
       });
       capturePhase2(phases, "session/create", sessionStartedAt);
       if (!sessionResponse.ok) {
@@ -9906,7 +10707,10 @@ function createServerTransportManager(options) {
       };
       context.telemetry?.captureTransport(transport);
       const startedAt = Date.now();
-      const response = await fetchLike(joinUrl(instance.origin, "/config/providers"));
+      const response = await fetchLike(
+        joinUrl(instance.origin, "/config/providers"),
+        { signal: context.abort.signal }
+      );
       capturePhase2(phases, "config/providers", startedAt);
       if (!response.ok) {
         throw new AiConnectError(
@@ -9950,6 +10754,15 @@ function createServerTransportManager(options) {
 }
 
 // src/local-handlers.ts
+function normalizeVerifyIssue(error, fallbackCode, fallbackMessage) {
+  const normalized = error instanceof AiConnectError ? error : new AiConnectError(fallbackCode, fallbackMessage);
+  return [
+    {
+      code: "handler_issue",
+      message: normalized.message
+    }
+  ];
+}
 function createLocalRouteHandlers(options = {}) {
   const acpTransport = createAcpTransportManager(options.acp);
   const cliTransport = createCliTransportManager(options.cli);
@@ -9980,16 +10793,11 @@ function createLocalRouteHandlers(options = {}) {
               }
             ];
           } catch (error) {
-            const normalized = error instanceof AiConnectError ? error : new AiConnectError(
+            return normalizeVerifyIssue(
+              error,
               "validation_error",
               "ACP route verification failed."
             );
-            return [
-              {
-                code: "handler_issue",
-                message: normalized.message
-              }
-            ];
           }
         }
       },
@@ -10028,16 +10836,11 @@ function createLocalRouteHandlers(options = {}) {
               }
             ];
           } catch (error) {
-            const normalized = error instanceof AiConnectError ? error : new AiConnectError(
+            return normalizeVerifyIssue(
+              error,
               "validation_error",
               "CLI route verification failed."
             );
-            return [
-              {
-                code: "handler_issue",
-                message: normalized.message
-              }
-            ];
           }
         }
       },
@@ -10073,16 +10876,11 @@ function createLocalRouteHandlers(options = {}) {
               }
             ];
           } catch (error) {
-            const normalized = error instanceof AiConnectError ? error : new AiConnectError(
+            return normalizeVerifyIssue(
+              error,
               "validation_error",
               "Server route verification failed."
             );
-            return [
-              {
-                code: "handler_issue",
-                message: normalized.message
-              }
-            ];
           }
         }
       }