talon-agent 5.24.0 → 5.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.24.0",
+  "version": "5.24.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/app.ts

@@ -74,6 +74,7 @@ import {
   writePidRecord,
   removePidRecordIfOwnedBy,
 } from "./core/daemon/pidfile.js";
+import { stampDaemonOwner } from "./core/daemon/pidfile.js";
 import {
   recordBootMetrics,
   startResourceSampler,
@@ -95,6 +96,24 @@ if (process.argv.includes(BOOT_SMOKE_FLAG)) {
   process.exit(0);
 }
 
+// One daemon per install. This runs before anything with a side effect
+// (restore, database, pidfile, trigger resume), because a second daemon
+// does damage in each of them — see checkSingleInstance in core/daemon/discovery.ts.
+{
+  const { checkSingleInstance, describeRefusal } =
+    await import("./core/daemon/discovery.js");
+  const verdict = await checkSingleInstance();
+  if (!verdict.ok) {
+    const message = describeRefusal(verdict.instance);
+    logError("bot", message);
+    console.error(`talon: ${message}`);
+    process.exit(1);
+  }
+}
+// Every child spawned from here on names this daemon as its owner, so an
+// orphan sweep can tell a dead daemon's leftovers from a live one's runs.
+stampDaemonOwner();
+
 /**
  * A `/backup restore <id>` from chat writes ~/.talon/restore-pending.json
  * and restarts. It is applied HERE, before anything else: every store
@@ -160,6 +179,17 @@ writePidRecord({ pid: process.pid, startedAt: bootedAt });
 // ── Create gateway + frontend ─────────────────────────────────────────────────
 
 const gateway = new Gateway("daemon");
+// Fail rather than fall back when the gateway port belongs to another
+// daemon: a fallback port is how a second daemon went unnoticed.
+gateway.setPortInUseCheck(async (port) => {
+  const { probeHealth } = await import("./core/daemon/discovery.js");
+  const health = await probeHealth(port);
+  return health?.app === "talon" &&
+    health.mode === "daemon" &&
+    health.pid !== process.pid
+    ? `gateway port ${port} is held by another Talon daemon (pid ${String(health.pid)})`
+    : undefined;
+});
 gateway.onStarted((port) =>
   writePidRecord({ pid: process.pid, port, startedAt: bootedAt }),
 );

package/src/backend/agy/process/orphans.ts

@@ -12,6 +12,7 @@
 
 import { readdir, readFile } from "node:fs/promises";
 import { log } from "../../../util/log.js";
+import { childBelongsToLiveDaemon } from "../../../core/daemon/pidfile.js";
 import { AGY_KILL_GRACE_MS } from "../constants.js";
 import { childChatIds, getChild } from "./child.js";
 
@@ -96,7 +97,10 @@ async function findOrphanPids(contextLabel: string): Promise<number[]> {
       // SIGKILL, so a chat id that happens to appear inside an
       // unrelated path must not select a victim.
       if (!argv.some((arg) => arg === "agy" || arg.endsWith("/agy"))) continue;
-      if (argv.includes(contextLabel)) matched.push(pid);
+      if (!argv.includes(contextLabel)) continue;
+      // Another running daemon's live run, not an orphan of ours.
+      if (childBelongsToLiveDaemon(pid)) continue;
+      matched.push(pid);
     } catch {
       // Exited between readdir and readFile, or not ours. Skip.
       continue;

package/src/backend/claude-sdk/one-shot.ts

@@ -22,6 +22,10 @@ import { buildMcpServers, buildPluginMcpServers } from "./options.js";
 import { isBackgroundToolContext } from "../../core/agents/context.js";
 import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
 import { emitAssistantText } from "../runtime/one-shot-hooks.js";
+import {
+  isOtherLiveDaemon,
+  ownerFromEnviron,
+} from "../../core/daemon/pidfile.js";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
 
@@ -290,8 +294,10 @@ async function formatAndAppendMessage(
  * triggers: the warden respawned them, the next sweep killed them again, and
  * the only visible symptom was a trigger stuck in "errored" with no output.
  *
- * Two independent guards, because this function issues SIGKILL:
+ * Three independent guards, because this function issues SIGKILL:
  *  - refuse anything tagged `TALON_TRIGGER_ID` (a trigger, or its child);
+ *  - refuse anything spawned by another daemon that is still running
+ *    (see core/daemon/pidfile.ts). Its "orphans" are that daemon's live runs;
  *  - require the argv to actually be the `claude` SDK binary, which is the
  *    only thing this sweep was ever meant to reap.
  */
@@ -304,6 +310,7 @@ export function isEvictableOrphan(
   if (envEntries.some((entry) => entry.startsWith("TALON_TRIGGER_ID="))) {
     return false;
   }
+  if (isOtherLiveDaemon(ownerFromEnviron(envEntries))) return false;
   return argv.some((arg) => arg === "claude" || arg.endsWith("/claude"));
 }
 

package/src/backend/codex/factory.ts

@@ -19,7 +19,10 @@ import {
   type ModelCatalog,
   type UsageTelemetry,
 } from "../../core/agent-runtime/capabilities.js";
-import { getPlanUsage as getCodexPlanUsage } from "./plan-usage.js";
+import {
+  getAuthFailure as getCodexAuthFailure,
+  getPlanUsage as getCodexPlanUsage,
+} from "./plan-usage.js";
 
 import { initCodexAgent, getCodexAuthInfo } from "./init.js";
 import { handleMessage as codexHandleMessage } from "./handler/index.js";
@@ -88,6 +91,7 @@ const codexFactory: BackendFactory = {
     // report its rate-limit windows.
     const usage: UsageTelemetry = {
       getPlanUsage: () => getCodexPlanUsage(),
+      getAuthFailure: () => getCodexAuthFailure(),
     };
 
     const backend = composeBackend({

package/src/backend/codex/plan-usage.ts

@@ -172,6 +172,18 @@ async function load(): Promise<PlanUsage | undefined> {
   }
 }
 
+/**
+ * Why the Codex login is known to be rejected, or `undefined`. Set by a 401
+ * from the usage endpoint and cleared once `codex login` rewrites
+ * auth.json (seen on the next {@link getPlanUsage} refresh). The router
+ * reads it to stop sending work to a backend whose runs can only fail.
+ */
+export function getAuthFailure(): string | undefined {
+  return rejectedAuthMtimeMs === undefined
+    ? undefined
+    : "Codex login expired (usage endpoint returned 401) — run `codex login`";
+}
+
 /**
  * Plan windows for `/usage`, cached for a minute. A failed refresh keeps
  * serving the last known values — `fetchedAt` lets the caller age them.

package/src/backend/runtime/turn/turn-phases.ts

@@ -26,7 +26,10 @@ import {
 } from "../../../storage/sessions.js";
 import { log } from "../../../util/log.js";
 import { extractSessionName } from "../../../core/weaver/session-name.js";
-import { recordBackendRunUsage } from "../../../core/engine/backend-router/index.js";
+import {
+  recordBackendRunSuccess,
+  recordBackendRunUsage,
+} from "../../../core/engine/backend-router/index.js";
 import { traceMessage } from "../../../util/trace.js";
 import {
   FLOW_VIOLATION_MAX_RETRIES,
@@ -120,6 +123,9 @@ export function accountTurn(inputs: AccountTurnInputs): void {
   // a provider with no account API still has a headroom signal. Backends
   // that DO report a plan simply outrank their own ledger.
   recordBackendRunUsage(inputs.backend, usage);
+  // A chat turn that completed is proof the backend works: close its
+  // breaker so background work may route there again.
+  if (!inputs.failed) recordBackendRunSuccess(inputs.backend);
   recordUsage(chatId, {
     ...usage,
     durationMs,

package/src/bootstrap.ts

@@ -155,6 +155,7 @@ export async function bootstrap(
       ...(config.operatorIds ?? []),
       ...(config.discord?.adminUserIds ?? []).map((id) => `discord:${id}`),
     ],
+    guardChildren: true,
   });
 
   initWorkspace(config.workspace);

package/src/cli.ts

@@ -16,22 +16,28 @@
  * `cli/index.ts`. Everything else lives under `cli/`.
  */
 
-import {
-  MCP_LAUNCH_SUBCOMMAND,
-  runSupervisor,
-} from "./core/mcp-hub/launcher.js";
-import { LUA_RUN_SUBCOMMAND, runLuaMain } from "./core/scripts/lua.js";
-
 // Hidden subcommand dispatch — must run before anything else. Talon
-// supervises MCP stdio children (`_mcp-launch`) and runs WASM-sandboxed
-// Lua trigger scripts (`_lua-run`) by re-invoking its own entrypoint
-// (see core/mcp-hub/launcher.ts). Neither call resolves; the helper process
-// exits from its own handlers.
-if (process.argv[2] === MCP_LAUNCH_SUBCOMMAND) {
+// supervises MCP stdio children (`_mcp-launch`, `_mcp-reaper`) and runs
+// WASM-sandboxed Lua trigger scripts (`_lua-run`) by re-invoking its own
+// entrypoint (see core/mcp-hub/launcher.ts). None of these calls resolves;
+// the helper process exits from its own handlers. Names are literals and
+// modules load dynamically so a helper process only evaluates its own
+// module (pinned to the exported constants by entry-dispatch.test.ts).
+const subcommand = process.argv[2];
+if (subcommand === "_mcp-launch") {
+  const { runSupervisor } = await import("./core/mcp-hub/launcher.js");
   await runSupervisor(process.argv.slice(3));
-} else if (process.argv[2] === LUA_RUN_SUBCOMMAND) {
+} else if (subcommand === "_mcp-reaper") {
+  const { runReaper } = await import("./core/mcp-hub/reaper.js");
+  await runReaper();
+} else if (subcommand === "_lua-run") {
+  const { runLuaMain } = await import("./core/scripts/lua.js");
   await runLuaMain(process.argv.slice(3));
 } else {
   const { runCli } = await import("./cli/index.js");
   await runCli();
 }
+
+// No static imports (see above) — mark the file as an ES module so
+// top-level await type-checks.
+export {};

package/src/core/agent-runtime/capabilities.ts

@@ -243,6 +243,13 @@ export interface UsageTelemetry {
    * plan concept; resolves `undefined` when the data can't be read.
    */
   getPlanUsage?(): Promise<PlanUsage | undefined>;
+  /**
+   * Why the backend's credential is known to be rejected (e.g. the usage
+   * endpoint returned 401), or `undefined` when nothing says it is.
+   * Synchronous and cheap: it reports what the last `getPlanUsage` saw.
+   * The router treats a backend that reports one as having no headroom.
+   */
+  getAuthFailure?(): string | undefined;
   /**
    * Banked one-shot limit resets, where the plan has them. Spending one is
    * irreversible, so this is reachable only from a human-pressed confirm

package/src/core/agents/runner.ts

@@ -35,6 +35,8 @@ import {
 } from "../engine/backend-controller/index.js";
 import {
   chooseBackend,
+  recordBackendRunFailure,
+  recordBackendRunSuccess,
   recordBackendRunUsage,
   taskClassForEffort,
 } from "../engine/backend-router/index.js";
@@ -437,9 +439,11 @@ async function runAgent(
         evictLabel: agentContextLabel(id),
       });
       recordBackendRunUsage(record.backendId, usage ?? undefined);
+      recordBackendRunSuccess(record.backendId);
       settled = settleSuccess(id, task, capture.last, usage ?? undefined);
     }
   } catch (err) {
+    recordBackendRunFailure(record.backendId, err);
     settled = settleFailure(id, task, err);
   } finally {
     await release().catch((err: unknown) =>

package/src/core/background/cron/job-oneshot.ts

@@ -19,7 +19,11 @@ import {
   acquireBackendInstance,
   isModelValidForBackend,
 } from "../../engine/backend-controller/index.js";
-import { recordBackendRunUsage } from "../../engine/backend-router/index.js";
+import {
+  recordBackendRunFailure,
+  recordBackendRunSuccess,
+  recordBackendRunUsage,
+} from "../../engine/backend-router/index.js";
 import { taskTable } from "../../tasks/index.js";
 import type { OneShotAgentParams } from "../../types.js";
 import { runIsolatedAgent } from "../isolated-agent.js";
@@ -184,8 +188,10 @@ async function attemptJobOneShot(
       });
       task.succeed(usage ?? undefined);
       recordBackendRunUsage(backendId, usage ?? undefined);
+      recordBackendRunSuccess(backendId);
     } catch (err) {
       task.fail(err);
+      recordBackendRunFailure(backendId, err);
       throw err;
     }
     log(

package/src/core/background/cron/scheduler.ts

@@ -223,15 +223,17 @@ async function runScheduled(job: CronJob): Promise<void> {
     }
     enforceRunCap(job.id);
   } catch (err) {
-    // Advance lastRunAt on failure too (without bumping runCount — failed runs
-    // don't count toward maxRuns). For interval jobs the anchor IS lastRunAt, so
-    // skipping this would make a flaky job re-fire every 60s tick until the
-    // breaker opens, instead of honoring its everyMs cadence between retries.
-    updateCronJob(job.id, {
-      lastRunAt: Date.now(),
-      lastStatus: "error",
-      lastError: err instanceof Error ? err.message : String(err),
-      lastDurationMs: Date.now() - startedAt,
+    // A failed run is still a run: it advances lastRunAt and bumps runCount,
+    // so it counts toward maxRuns. For interval jobs the anchor IS lastRunAt,
+    // so not advancing it would make a flaky job re-fire every 60s tick until
+    // the breaker opens. And a capped job — a one-shot above all — whose
+    // failure didn't count would stay enabled and fire again at the next
+    // matching time: for a date-pinned cron expression that is a year later,
+    // long after anyone wanted it.
+    recordCronRun(job.id, {
+      status: "error",
+      error: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - startedAt,
     });
     logError(
       "cron",
@@ -252,6 +254,14 @@ async function runScheduled(job: CronJob): Promise<void> {
         `Cron job "${job.name}" failed ${JOB_HEALTH.threshold} runs in a row: ${faultText(err)}. Paused for ~${mins} min.`,
       );
     }
+    if (enforceRunCap(job.id)) {
+      // The job's last permitted run failed and it is now retired — nothing
+      // will retry it, so the operator has to hear about it.
+      raiseAlert(
+        `cron.job.${job.id}`,
+        `Cron job "${job.name}" failed on its final run and was disabled: ${faultText(err)}. Re-enable or recreate it to try again.`,
+      );
+    }
   } finally {
     runningJobs.delete(job.id);
   }
@@ -261,11 +271,12 @@ async function runScheduled(job: CronJob): Promise<void> {
 
 /**
  * Disable a job that has reached its run cap (`maxRuns`; =1 means one-shot).
- * Call after a successful run, once runCount has been bumped.
+ * Call after every run — successful or failed — once runCount has been
+ * bumped. Returns true when this call retired the job.
  */
-function enforceRunCap(id: string): void {
+function enforceRunCap(id: string): boolean {
   const job = getCronJob(id);
-  if (!job || !job.enabled) return;
+  if (!job || !job.enabled) return false;
   if (job.maxRuns !== undefined && job.runCount >= job.maxRuns) {
     updateCronJob(id, { enabled: false });
     log(
@@ -276,7 +287,9 @@ function enforceRunCap(id: string): void {
       "Cron",
       `Job "${job.name}" finished after ${job.runCount} run(s)`,
     );
+    return true;
   }
+  return false;
 }
 
 /**
@@ -522,7 +535,8 @@ async function routeQueryJob(
   return { backendId: decision.backendId, model };
 }
 
-const CRON_JOB_TIMEOUT_MS = 10 * 60_000; // 10-minute max per job
+/** Default hard limit per query run; a job's own `timeoutMs` overrides it. */
+const CRON_JOB_TIMEOUT_MS = 10 * 60_000;
 
 export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
   if (!deps) return { status: "skipped", reason: "cron is not initialised" };
@@ -577,7 +591,7 @@ export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
     payload,
     label: job.name,
     kind: "cron",
-    timeoutMs: CRON_JOB_TIMEOUT_MS,
+    timeoutMs: job.timeoutMs ?? CRON_JOB_TIMEOUT_MS,
     ...(fallback ? { fallback } : {}),
   });
   if (result.status === "skipped") {

package/src/core/background/cron/spec.ts

@@ -24,6 +24,9 @@ import {
 const MIN_INTERVAL_SECONDS = 60;
 const MAX_CONTENT_LENGTH = 10_000;
 const CATCHUP_POLICIES = new Set<CatchupPolicy>(["skip", "once", "all"]);
+/** Per-job run timeout bounds (seconds). The scheduler default is 10 minutes. */
+const MIN_TIMEOUT_SECONDS = 60;
+const MAX_TIMEOUT_SECONDS = 4 * 60 * 60;
 
 /** The job fields the spec covers; everything else is identity or telemetry. */
 type CronSpec = Pick<CronJob, "name" | "type" | "content" | "catchup"> &
@@ -40,6 +43,7 @@ type CronSpec = Pick<CronJob, "name" | "type" | "content" | "catchup"> &
       | "model"
       | "provider"
       | "instructions"
+      | "timeoutMs"
     >
   >;
 
@@ -220,8 +224,8 @@ const parseCatchup: Section = ({ body, editing, touched, updates }) => {
 };
 
 /**
- * Model / provider / instructions only make sense for "query" jobs (a
- * "message" job just sends text — no model runs), and a provider override
+ * Model / provider / instructions / timeout only make sense for "query" jobs
+ * (a "message" job just sends text — no model runs), and a provider override
  * needs a model to pick on it.
  */
 const parseOverrides: Section = (p) => {
@@ -230,9 +234,25 @@ const parseOverrides: Section = (p) => {
     if (touched(key))
       updates[key] = provided(body[key]) ? String(body[key]) : undefined;
   }
-  const { type, model, provider, instructions } = merge(p);
+  if (touched("timeout_seconds")) {
+    if (!provided(body.timeout_seconds)) {
+      updates.timeoutMs = undefined;
+    } else {
+      const secs = Number(body.timeout_seconds);
+      if (
+        !Number.isFinite(secs) ||
+        secs < MIN_TIMEOUT_SECONDS ||
+        secs > MAX_TIMEOUT_SECONDS
+      )
+        return `'timeout_seconds' must be a number between ${MIN_TIMEOUT_SECONDS} and ${MAX_TIMEOUT_SECONDS}.`;
+      updates.timeoutMs = Math.round(secs * 1000);
+    }
+  }
+  const { type, model, provider, instructions, timeoutMs } = merge(p);
   if (type !== "query" && (model || provider || instructions))
     return "Model/provider/instructions only apply to 'query' jobs.";
+  if (type !== "query" && timeoutMs !== undefined)
+    return "'timeout_seconds' only applies to 'query' jobs.";
   if (provider && !model)
     return "A 'provider' override also requires a 'model'.";
   return null;

package/src/core/background/heartbeat/agent.ts

@@ -18,6 +18,8 @@ import type { OneShotAgentParams } from "../../types.js";
 import { acquireBackendInstance } from "../../engine/backend-controller/index.js";
 import {
   chooseBackend,
+  recordBackendRunFailure,
+  recordBackendRunSuccess,
   recordBackendRunUsage,
   resolveRoutedModel,
 } from "../../engine/backend-router/index.js";
@@ -471,6 +473,9 @@ export async function runHeartbeatAgent(
       runCount,
       heartbeatLogFile,
     );
+  } catch (err) {
+    recordBackendRunFailure(target.backendId, err);
+    throw err;
   } finally {
     // A routed run borrowed the instance from the pool; hand it back on
     // every path or the provider stays warm until the daemon restarts.
@@ -483,6 +488,7 @@ export async function runHeartbeatAgent(
     }
   }
   recordBackendRunUsage(target.backendId, usage ?? undefined);
+  recordBackendRunSuccess(target.backendId);
   task.succeed(usage ?? undefined);
   return heartbeatLogFile;
 }

package/src/core/background/triggers/resume.ts

@@ -1,8 +1,8 @@
 /**
  * Post-restart resume — respawn persistent triggers, fire late wakes for
  * recently-terminated ones, plus the orphan-kill used to avoid duplicate
- * spawns after an unclean crash. The /proc PID-starttime probe both this
- * and spawn use lives in ./pid.ts.
+ * spawns after an unclean crash. The /proc probes it relies on (pid start
+ * time, owning daemon) live in core/daemon/pidfile.ts.
  */
 
 import {
@@ -12,11 +12,14 @@ import {
   SHUTDOWN_KILL_ERROR,
   type Trigger,
 } from "../../../storage/triggers.js";
-import { log, logError } from "../../../util/log.js";
+import { log, logError, logWarn } from "../../../util/log.js";
 import { depsHolder } from "./state.js";
 import { fireWake } from "./output.js";
 import { spawnTrigger } from "./spawn.js";
-import { readPidStarttimeSync } from "./pid.js";
+import {
+  childBelongsToLiveDaemon,
+  readPidStarttimeSync,
+} from "../../../core/daemon/pidfile.js";
 
 /**
  * After the dispatcher is wired, walk the store and clean up leftover state
@@ -85,6 +88,11 @@ export async function resumeAfterRestart(): Promise<void> {
  * boot and unchanged by exec(), so a match means the PID still belongs to our
  * process. On non-Linux (no /proc), pidStarttime is undefined and we fall
  * through to SIGKILL.
+ *
+ * Owner check: a process whose spawning daemon is still alive is not an
+ * orphan. It is another daemon's live trigger. That is what a second,
+ * concurrently started daemon found on 2026-09-27, and it SIGKILLed the
+ * running daemon's watchers.
  */
 function killOrphan(t: Trigger): void {
   if (t.pid === undefined) return;
@@ -93,6 +101,13 @@ function killOrphan(t: Trigger): void {
   } catch {
     return; // dead — nothing to do
   }
+  if (childBelongsToLiveDaemon(t.pid)) {
+    logWarn(
+      "triggers",
+      `Orphan probe: pid=${t.pid} ("${t.name}") belongs to another running daemon — leaving alone`,
+    );
+    return;
+  }
   if (t.pidStarttime !== undefined) {
     const current = readPidStarttimeSync(t.pid);
     if (current !== undefined && current !== t.pidStarttime) {

package/src/core/background/triggers/spawn.ts

@@ -25,7 +25,7 @@ import {
 import { commandForLanguage } from "./command.js";
 import { handleStdoutLine, handleStderrLine } from "./output.js";
 import { handleTimeout, finalizeExit, failTrigger } from "./exit.js";
-import { readPidStarttimeSync } from "./pid.js";
+import { readPidStarttimeSync } from "../../../core/daemon/pidfile.js";
 
 /**
  * Spawn a trigger's script as a supervised child process.

package/src/core/config/index.ts

@@ -318,6 +318,80 @@ const whatsappConfigSchema = z
   })
   .strict();
 
+/** `fetch` — the fetch ladder behind `fetch_url` (docs/fetch-ladder.md). */
+export const fetchConfigSchema = z
+  .object({
+    /** Browser-TLS impersonation via curl-impersonate (default true). */
+    impersonate: z.boolean().default(true),
+    /** curl-impersonate profiles for the direct rung, tried in order. */
+    impersonateTargets: z
+      .array(
+        z
+          .string()
+          .regex(
+            /^[a-z0-9_]+$/,
+            "a curl-impersonate target name, e.g. safari184",
+          ),
+      )
+      .min(1)
+      .optional(),
+    /** Use this curl-impersonate binary instead of the first-use download. */
+    curlImpersonatePath: z.string().trim().min(1).optional(),
+    /**
+     * SOCKS exits for the impersonation rung, e.g.
+     * "socks5h://socks-nl1.nordvpn.com:1080". Credentials are never
+     * accepted here: they come from TALON_FETCH_SOCKS_USER /
+     * TALON_FETCH_SOCKS_PASS or `socksCredentialsFile` (one line,
+     * "user:pass").
+     */
+    socksExits: z
+      .array(
+        z
+          .string()
+          .trim()
+          .refine((value) => {
+            try {
+              return /^socks(4a?|5h?):$/.test(new URL(value).protocol);
+            } catch {
+              return false;
+            }
+          }, "must be a socks5h://, socks5://, socks4a:// or socks4:// URL")
+          .refine((value) => {
+            try {
+              const u = new URL(value);
+              return !u.username && !u.password;
+            } catch {
+              return true;
+            }
+          }, "must not contain credentials — set TALON_FETCH_SOCKS_USER/TALON_FETCH_SOCKS_PASS or fetch.socksCredentialsFile"),
+      )
+      .default([]),
+    socksCredentialsFile: z.string().trim().min(1).optional(),
+    /**
+     * Anti-detect browser rung: connect to the Camoufox/Playwright server
+     * at `browserEndpoint` (default: the playwright plugin's endpoint).
+     */
+    camoufox: z.boolean().default(false),
+    browserEndpoint: z.string().trim().min(1).optional(),
+    /**
+     * Last resort: run curl on this mesh device (id or name). Off unless
+     * set — the device's owner pays for the traffic and the IP.
+     */
+    egressDevice: z.string().trim().min(1).optional(),
+    /**
+     * Daily cap (bytes) on traffic through relayed rungs (SOCKS exits and
+     * the egress device). 0 disables those rungs. Direct rungs are
+     * uncapped. The counter is in-memory and resets at UTC midnight and
+     * on restart.
+     */
+    dailyByteCap: z
+      .number()
+      .int()
+      .min(0)
+      .default(100 * 1024 * 1024),
+  })
+  .strict();
+
 const playwrightConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /** Browser engine: chromium (default), chrome, firefox, webkit, msedge */
@@ -690,6 +764,14 @@ const configSchema = z.object({
     .object({ allowPrivateNetworks: z.boolean().default(true) })
     .strict()
     .optional(),
+  /**
+   * The fetch ladder behind `fetch_url` (docs/fetch-ladder.md): when a page
+   * answers with a bot wall it retries through browser-TLS impersonation,
+   * SOCKS exits, a plain fetch, an anti-detect browser and — only if set —
+   * a mesh device, in that order. Everything but impersonation is off
+   * until configured.
+   */
+  fetch: fetchConfigSchema.optional(),
   /**
    * Codex-specific OpenAI API key. Prefer this, CODEX_API_KEY, or
    * TALON_CODEX_KEY when the Codex backend should use API-key billing