<!--
title: Defensive config handling
domain: ai-agents
topic: Configurations
language: TypeScript
source: coleam00/Archon
updated: 2026-05-01
url: https://awesomereviewers.com/reviewers/archon-defensive-config-handling/
-->

Configuration should be treated as untrusted input: validate and normalize it, ignore unknown/invalid fields, and ensure user misconfiguration can’t crash initialization or produce misleading warnings. Also gate checks by what’s actually configured and implement a clear precedence order (env → explicit config → user paths → canonical defaults → PATH lookup) with platform-correct behavior.

Apply it like this:
- Parse YAML/env into typed config by checking `typeof` and only assigning known fields.
- For numeric settings, enforce constraints (e.g., finite and positive), normalize (e.g., truncate fractional seconds/ms), and cover invalid cases with regression tests.
- Never throw during provider/provider-discovery/config parsing; drop invalid fields instead.
- When performing environment-dependent checks, only warn when the relevant credentials/config are expected to exist; if an alternate forge is configured and GitHub token is absent, skip the GitHub-specific warning.
- When resolving external binaries, follow a documented precedence chain starting with explicit overrides, then fall back safely; ensure OS-specific lookup (e.g., Windows `where` resolving shims) is correct.

Example pattern (parser + guard):
```ts
export function parseTimeouts(raw: Record<string, unknown>) {
  const out: { firstEventTimeoutMs?: number; processTimeoutMs?: number } = {};

  const toFinitePositiveMs = (v: unknown) =>
    typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.trunc(v) : undefined;

  const first = toFinitePositiveMs(raw.firstEventTimeoutMs);
  if (first !== undefined) out.firstEventTimeoutMs = first;

  const proc = toFinitePositiveMs(raw.processTimeoutMs);
  if (proc !== undefined) out.processTimeoutMs = proc;

  return out;
}

function shouldCheckGhAuth() {
  const hasGhToken = !!(process.env.GH_TOKEN || process.env.GITHUB_TOKEN);
  const hasOtherForge = !!(process.env.GITEA_URL || process.env.GITLAB_URL);
  return hasGhToken || !hasOtherForge; // skip GH warning for non-GH-only setups
}
```