talon-agent 5.23.1 → 5.24.1

package/src/cli/skill.ts

@@ -15,7 +15,7 @@
 
 import pc from "picocolors";
 import { existsSync, readdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import {
   deleteSkill,
   installSkillFromDir,
@@ -23,7 +23,13 @@ import {
   setSkillEnabled,
   type Skill,
 } from "../storage/skills.js";
-import { cloneShallow, resolveSource } from "./install-sources.js";
+import {
+  cloneSource,
+  resolveSource,
+  withCommit,
+  writeInstallRecord,
+  type GitSource,
+} from "./install-sources.js";
 
 const USAGE = [
   `  Usage: ${pc.cyan("talon skill <command>")}`,
@@ -32,6 +38,7 @@ const USAGE = [
   `    ${pc.cyan("list")}                       Show installed skills`,
   `    ${pc.cyan("install <source> [--force]")} Add skills from a local folder,`,
   "                               git URL, or owner/repo[/subpath]",
+  `    ${pc.cyan("  [--commit <sha>]")}         …at this commit (or <source>#<sha>)`,
   `    ${pc.cyan("enable <name>")}              Restore a skill to the prompt index`,
   `    ${pc.cyan("disable <name>")}             Hide a skill from the prompt index`,
   `    ${pc.cyan("remove <name>")}              Delete a skill folder`,
@@ -119,16 +126,61 @@ function installAll(dirs: string[], force: boolean): Skill[] {
   return installed;
 }
 
+type SkillInstallArgs = { source: string; force: boolean; commit?: string };
+
+function parseInstallArgs(args: string[]): SkillInstallArgs | null {
+  let source: string | undefined;
+  let force = false;
+  let commit: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--force") force = true;
+    else if (arg === "--commit") commit = args[++i];
+    else if (!arg.startsWith("-") && source === undefined) source = arg;
+    else return null;
+  }
+  if (!source || (commit !== undefined && !commit)) return null;
+  return { source, force, ...(commit !== undefined ? { commit } : {}) };
+}
+
+/**
+ * Record, in each skill folder of the clone, which repo and commit it came
+ * from — before it is copied into the store.
+ */
+function recordProvenance(
+  source: GitSource,
+  root: string,
+  dirs: string[],
+  commit: string | undefined,
+): void {
+  for (const dir of dirs) {
+    const subpath = relative(root, dir).split(sep).join("/");
+    const inRepo = [source.subpath, subpath].filter(Boolean).join("/");
+    writeInstallRecord(dir, {
+      source: source.url,
+      ...(inRepo ? { subpath: inRepo } : {}),
+      ...(commit ? { commit } : {}),
+      ...(source.commit ? { pinned: true } : {}),
+    });
+  }
+}
+
 async function cmdInstall(args: string[]): Promise<void> {
-  const force = args.includes("--force");
-  const source = args.find((arg) => !arg.startsWith("-"));
-  if (!source) {
+  const parsed = parseInstallArgs(args);
+  if (!parsed) {
     console.log(USAGE);
     process.exitCode = 1;
     return;
   }
+  const { source, force } = parsed;
 
-  const resolved = resolveSource(source);
+  const pinned = withCommit(resolveSource(source), parsed.commit);
+  if (!pinned.ok) {
+    fail(pinned.error);
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = pinned.source;
   if (resolved.kind === "other") {
     fail(
       `"${source}" is not a folder, git URL, or owner/repo — skills install from SKILL.md folders.`,
@@ -147,7 +199,7 @@ async function cmdInstall(args: string[]): Promise<void> {
     }
     installed = installAll(dirs, force);
   } else {
-    const clone = cloneShallow(resolved.url);
+    const clone = cloneSource(resolved);
     if (!clone.ok) {
       fail(clone.error);
       process.exitCode = 1;
@@ -170,6 +222,7 @@ async function cmdInstall(args: string[]): Promise<void> {
         process.exitCode = 1;
         return;
       }
+      recordProvenance(resolved, root, dirs, clone.commit);
       installed = installAll(dirs, force);
       if (clone.commit) {
         console.log(`  ${pc.dim(`From ${resolved.url} @ ${clone.commit}`)}`);

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

@@ -154,7 +154,8 @@ const frontendEnum = z.enum([
  *
  * Defaults are loopback-only and unauthenticated (single-machine use). To
  * reach Talon remotely, set `host: "0.0.0.0"` and a `token` — the bridge
- * then requires `Authorization: Bearer <token>` (or `?token=` for SSE).
+ * then requires `Authorization: Bearer <token>` (or `?token=` on `GET /events`
+ * and `GET /media` only, where clients can't set a header).
  * A non-loopback bind with no token auto-mints a persistent one
  * (~/.talon/keys/bridge-token) rather than serving the LAN open.
  */
@@ -170,9 +171,10 @@ const nativeConfigSchema = z
     host: z.string().default("127.0.0.1"),
     /**
      * Optional shared secret. When set, every request must present it as a
-     * bearer token (header) or `?token=` query param (SSE). When unset on a
-     * non-loopback `host`, the bridge mints and persists one automatically
-     * (~/.talon/keys/bridge-token) — the network never gets an open bridge.
+     * bearer token (header), or a `?token=` query param on `GET /events` and
+     * `GET /media` only. When unset on a non-loopback `host`, the bridge
+     * mints and persists one automatically (~/.talon/keys/bridge-token) —
+     * the network never gets an open bridge.
      */
     token: z.string().optional(),
     /**
@@ -316,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 */
@@ -688,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