talon-agent 5.23.0 → 5.24.0

package/README.md

@@ -88,7 +88,9 @@ xattr -d com.apple.quarantine ./talon-darwin-arm64
 ```
 
 Verify a direct download against the release `SHA256SUMS`:
-`sha256sum -c SHA256SUMS --ignore-missing`.
+`sha256sum -c SHA256SUMS --ignore-missing`, and its build provenance with
+`gh attestation verify talon-linux-x64 --repo thefalconry/talon` (see
+[SECURITY.md](SECURITY.md#verifying-a-release)).
 
 **Server only, no Telegram?** Run the daemon with just the client bridge,
 reached by the companion app and talon-node: see
@@ -272,6 +274,7 @@ daemon (plugins) or apply on the next session (skills):
 talon plugin install @scope/my-talon-plugin        # npm → module plugin
 talon plugin install some-mcp-server --mcp         # npm → standalone MCP server (npx)
 talon plugin install owner/repo                    # git → module plugin
+talon plugin install owner/repo#<sha>              # …at that commit (or --commit <sha>)
 talon plugin list                                  # built-ins + configured entries
 talon plugin disable github                        # also toggles built-ins
 talon plugin remove my-talon-plugin
@@ -285,7 +288,10 @@ talon skill remove pdf
 ```
 
 Module plugins install under `~/.talon/plugins/`; standalone MCP servers are
-registered as `npx` entries in `config.json`. Disabling keeps the entry (or a
+registered as `npx` entries in `config.json`. A git source can be pinned to a
+commit with `#<sha>` or `--commit <sha>` (7-64 hex digits): Talon checks that
+commit out and verifies HEAD before installing. Either way the install
+folder's `.talon-install.json` records the repo and the exact commit. Disabling keeps the entry (or a
 `.disabled` marker in the skill folder) so enabling restores it unchanged.
 
 ## Built-in Plugins

package/package.json

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

package/src/cli/install-sources.ts

@@ -10,11 +10,17 @@
  *   4. anything else                         → { kind: "other" } — the caller
  *      decides (plugins treat it as an npm spec, skills reject it)
  *
- * Cloning always uses `--depth=1` (installs never need history), ends the
- * options with `--` so a URL can never be read as a git flag, and reports
- * the commit it got so the install can be pinned/audited later. It spawns
- * `git`/`npm` via cross-spawn, which resolves the `.cmd`/`.exe` shims on
- * Windows — never assume a POSIX shell here.
+ * A git source may name a commit: `<source>#<sha>` (7-64 hex digits), or
+ * `--commit <sha>` on the command line (`withCommit`).
+ *
+ * Without a commit, cloning uses `--depth=1` (installs never need history).
+ * With one, it clones with `--filter=blob:none` (history, but only the
+ * blobs of the commit it checks out), checks the commit out and verifies
+ * HEAD is that commit. Either way the options end with `--` so a URL can
+ * never be read as a git flag, a URL starting with "-" is refused before
+ * git runs, and the commit it got is reported so the install can record
+ * it. It spawns `git`/`npm` via cross-spawn, which resolves the
+ * `.cmd`/`.exe` shims on Windows — never assume a POSIX shell here.
  */
 
 import crossSpawn from "cross-spawn";
@@ -22,40 +28,84 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
+export type GitSource = {
+  kind: "git";
+  url: string;
+  subpath?: string;
+  /** Requested commit (lowercase hex, 7-64 digits); unset = default branch. */
+  commit?: string;
+};
+
 export type ResolvedSource =
-  | { kind: "local"; dir: string }
-  | { kind: "git"; url: string; subpath?: string }
-  | { kind: "other"; raw: string };
+  { kind: "local"; dir: string } | GitSource | { kind: "other"; raw: string };
 
 const GIT_URL_RE = /^(https?|git|ssh):\/\//;
 /** `owner/repo` or `owner/repo/sub/path` — never an npm scope (`@…`). */
 const GITHUB_SHORTHAND_RE =
   /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)((?:\/[^\s/]+)*)$/;
+/** An abbreviated or full commit id (SHA-1 or SHA-256). */
+const COMMIT_RE = /^[0-9a-f]{7,64}$/;
+/** `<source>#<commit>` — only a hex fragment is a pin. */
+const COMMIT_FRAGMENT_RE = /^(.+)#([0-9a-fA-F]{7,64})$/;
+
+function gitSource(spec: string): GitSource | undefined {
+  if (
+    GIT_URL_RE.test(spec) ||
+    spec.startsWith("git@") ||
+    spec.endsWith(".git")
+  ) {
+    return { kind: "git", url: spec };
+  }
+  if (spec.startsWith("@")) return undefined;
+  const match = GITHUB_SHORTHAND_RE.exec(spec);
+  if (!match) return undefined;
+  const [, owner, repo, rest] = match;
+  return {
+    kind: "git",
+    url: `https://github.com/${owner}/${repo}.git`,
+    ...(rest ? { subpath: rest.slice(1) } : {}),
+  };
+}
 
 export function resolveSource(raw: string): ResolvedSource {
   const trimmed = raw.trim();
   if (existsSync(resolve(trimmed))) {
     return { kind: "local", dir: resolve(trimmed) };
   }
-  if (
-    GIT_URL_RE.test(trimmed) ||
-    trimmed.startsWith("git@") ||
-    trimmed.endsWith(".git")
-  ) {
-    return { kind: "git", url: trimmed };
+  const pinned = COMMIT_FRAGMENT_RE.exec(trimmed);
+  if (pinned) {
+    const git = gitSource(pinned[1]!);
+    if (git) return { ...git, commit: pinned[2]!.toLowerCase() };
+  }
+  return gitSource(trimmed) ?? { kind: "other", raw: trimmed };
+}
+
+/**
+ * Apply a `--commit <sha>` flag to a resolved source: only git sources
+ * take one, and it must agree with a `#<sha>` already in the source.
+ */
+export function withCommit(
+  source: ResolvedSource,
+  commit: string | undefined,
+): { ok: true; source: ResolvedSource } | { ok: false; error: string } {
+  if (commit === undefined) return { ok: true, source };
+  const sha = commit.trim().toLowerCase();
+  if (!COMMIT_RE.test(sha)) {
+    return {
+      ok: false,
+      error: `"${commit}" is not a commit id (7-64 hex digits)`,
+    };
+  }
+  if (source.kind !== "git") {
+    return { ok: false, error: "--commit only applies to git sources" };
   }
-  if (!trimmed.startsWith("@")) {
-    const match = GITHUB_SHORTHAND_RE.exec(trimmed);
-    if (match) {
-      const [, owner, repo, rest] = match;
-      return {
-        kind: "git",
-        url: `https://github.com/${owner}/${repo}.git`,
-        ...(rest ? { subpath: rest.slice(1) } : {}),
-      };
-    }
+  if (source.commit !== undefined && source.commit !== sha) {
+    return {
+      ok: false,
+      error: `--commit ${sha} conflicts with #${source.commit} in the source`,
+    };
   }
-  return { kind: "other", raw: trimmed };
+  return { ok: true, source: { ...source, commit: sha } };
 }
 
 export type CommandOutcome = { ok: true } | { ok: false; error: string };
@@ -105,16 +155,56 @@ function headCommit(dir: string): string | undefined {
   return sha && /^[0-9a-f]{40,64}$/.test(sha) ? sha : undefined;
 }
 
+/** Whether the clone already has `commit` (no network). */
+function hasCommit(dir: string, commit: string): boolean {
+  return (
+    crossSpawn.sync(
+      "git",
+      ["-C", dir, "cat-file", "-e", `${commit}^{commit}`],
+      {
+        stdio: "ignore",
+      },
+    ).status === 0
+  );
+}
+
+/**
+ * `--` stops git's option parsing; refusing a leading dash too means a
+ * hostile "URL" never even reaches git.
+ */
+function dashRefusal(url: string): CloneOutcome | undefined {
+  return url.startsWith("-")
+    ? { ok: false, error: `Refusing a git URL that starts with "-"` }
+    : undefined;
+}
+
+/**
+ * Check out bytes exactly as committed. Windows git defaults to
+ * core.autocrlf=true, which rewrites LF to CRLF on checkout — a pinned
+ * install would then differ from the commit it names, and CRLF frontmatter
+ * fails to parse as a skill. `clone -c` writes this into the new repo's
+ * config, so the later `checkout` honours it too.
+ */
+const EXACT_BYTES = ["-c", "core.autocrlf=false"];
+
+function tempCloneDir(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "talon-install-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
 /** Shallow-clone into a fresh temp directory. Caller must run `cleanup`. */
 export function cloneShallow(url: string): CloneOutcome {
-  // `--` below already stops option parsing; refusing a leading dash too
-  // means a hostile "URL" never even reaches git.
-  if (url.startsWith("-")) {
-    return { ok: false, error: `Refusing a git URL that starts with "-"` };
-  }
-  const dir = mkdtempSync(join(tmpdir(), "talon-install-"));
-  const cleanup = () => rmSync(dir, { recursive: true, force: true });
-  const outcome = runTool("git", ["clone", "--depth=1", "--", url, dir]);
+  const refused = dashRefusal(url);
+  if (refused) return refused;
+  const { dir, cleanup } = tempCloneDir();
+  const outcome = runTool("git", [
+    "clone",
+    ...EXACT_BYTES,
+    "--depth=1",
+    "--",
+    url,
+    dir,
+  ]);
   if (!outcome.ok) {
     cleanup();
     return { ok: false, error: `Clone failed: ${outcome.error}` };
@@ -122,13 +212,75 @@ export function cloneShallow(url: string): CloneOutcome {
   return { ok: true, dir, commit: headCommit(dir), cleanup };
 }
 
+/**
+ * Clone and check out exactly `commit`, verifying HEAD is that commit.
+ * Caller must run `cleanup`. The clone keeps history (a commit can be
+ * anywhere in it) but fetches file contents only for the checked-out tree.
+ */
+export function cloneAtCommit(url: string, commit: string): CloneOutcome {
+  const refused = dashRefusal(url);
+  if (refused) return refused;
+  const { dir, cleanup } = tempCloneDir();
+  const fail = (error: string): CloneOutcome => {
+    cleanup();
+    return { ok: false, error };
+  };
+  const cloned = runTool("git", [
+    "clone",
+    ...EXACT_BYTES,
+    "--filter=blob:none",
+    "--no-checkout",
+    "--",
+    url,
+    dir,
+  ]);
+  if (!cloned.ok) return fail(`Clone failed: ${cloned.error}`);
+  if (!hasCommit(dir, commit) && commit.length >= 40) {
+    // A commit no branch reaches (a PR head, say): ask for it by id.
+    runTool("git", ["-C", dir, "fetch", "-q", "origin", commit]);
+  }
+  const checkout = runTool("git", [
+    "-C",
+    dir,
+    "checkout",
+    "-q",
+    "--detach",
+    commit,
+    "--",
+  ]);
+  if (!checkout.ok) {
+    return fail(`Commit ${commit} not found in ${url}: ${checkout.error}`);
+  }
+  const head = headCommit(dir);
+  if (!head?.startsWith(commit)) {
+    return fail(`Checked out ${head ?? "nothing"}, not commit ${commit}`);
+  }
+  return { ok: true, dir, commit: head, cleanup };
+}
+
+/** Clone a git source: at its requested commit, else the default branch. */
+export function cloneSource(source: GitSource): CloneOutcome {
+  return source.commit
+    ? cloneAtCommit(source.url, source.commit)
+    : cloneShallow(source.url);
+}
+
 /** The file a git-installed plugin keeps its provenance in. */
 const INSTALL_RECORD = ".talon-install.json";
 
-/** Write where an install came from and exactly which commit it is. */
+/**
+ * Write where an install came from and exactly which commit it is.
+ * `pinned` marks a commit the user asked for, rather than whatever the
+ * default branch pointed at.
+ */
 export function writeInstallRecord(
   dir: string,
-  record: { source: string; subpath?: string; commit?: string },
+  record: {
+    source: string;
+    subpath?: string;
+    commit?: string;
+    pinned?: boolean;
+  },
 ): void {
   writeFileSync(
     join(dir, INSTALL_RECORD),

package/src/cli/plugin.ts

@@ -12,7 +12,9 @@
  * Install sources (see cli/install-sources.ts for the shared grammar):
  * local path and git checkouts become module entries under ~/.talon/plugins;
  * an npm spec installs there too, or registers an `npx` MCP entry with
- * `--mcp`. Windows-safe throughout — tools are spawned via cross-spawn.
+ * `--mcp`. A cloned source installs at a given commit with `#<sha>` or
+ * `--commit <sha>`. Windows-safe throughout — tools are spawned via
+ * cross-spawn.
  */
 
 import pc from "picocolors";
@@ -24,11 +26,12 @@ import { findRunningInstance } from "../core/daemon/discovery.js";
 import { fetchGateway } from "./daemon-api.js";
 import { loadConfig, saveConfig, type Config } from "./config.js";
 import {
-  cloneShallow,
+  cloneSource,
   writeInstallRecord,
   resolveSource,
+  withCommit,
   runTool,
-  type ResolvedSource,
+  type GitSource,
 } from "./install-sources.js";
 import {
   BUILTIN_PLUGINS,
@@ -50,7 +53,8 @@ const USAGE = [
   "  Commands:",
   `    ${pc.cyan("list")}                       Show built-ins and configured plugins`,
   `    ${pc.cyan("install <source>")}           Add a plugin (local path, git URL,`,
-  "                               owner/repo, or npm spec)",
+  "                               owner/repo, or npm spec); a git source",
+  "                               may end in #<commit>",
   `    ${pc.cyan("enable <name>")}              Enable a plugin`,
   `    ${pc.cyan("disable <name>")}             Disable a plugin (kept in config)`,
   `    ${pc.cyan("remove <name>")}              Remove a plugin entry (and its install)`,
@@ -60,6 +64,7 @@ const USAGE = [
   "                               MCP server (npx) instead of a module",
   `    ${pc.cyan("--name <name>")}              Override the derived plugin name`,
   `    ${pc.cyan("--force")}                    Replace an existing install/entry`,
+  `    ${pc.cyan("--commit <sha>")}             Install a git source at this commit`,
   "",
 ].join("\n");
 
@@ -184,7 +189,12 @@ function cmdList(): void {
 
 // ── install ─────────────────────────────────────────────────────────────────
 
-type InstallFlags = { mcp: boolean; force: boolean; name?: string };
+type InstallFlags = {
+  mcp: boolean;
+  force: boolean;
+  name?: string;
+  commit?: string;
+};
 
 function parseInstallArgs(
   args: string[],
@@ -196,10 +206,12 @@ function parseInstallArgs(
     if (arg === "--mcp") flags.mcp = true;
     else if (arg === "--force") flags.force = true;
     else if (arg === "--name") flags.name = args[++i];
+    else if (arg === "--commit") flags.commit = args[++i];
     else if (!arg.startsWith("-") && source === undefined) source = arg;
     else return null;
   }
   if (!source || (flags.name !== undefined && !flags.name)) return null;
+  if (flags.commit !== undefined && !flags.commit) return null;
   return { source, flags };
 }
 
@@ -229,10 +241,7 @@ function installFromLocalDir(dir: string): EntryOutcome {
  * once the staged copy is known-good, so a failed install never destroys
  * a working one.
  */
-function installFromGit(
-  source: Extract<ResolvedSource, { kind: "git" }>,
-  flags: InstallFlags,
-): EntryOutcome {
+function installFromGit(source: GitSource, flags: InstallFlags): EntryOutcome {
   const derived = source.subpath
     ? basename(source.subpath)
     : basename(source.url, ".git");
@@ -245,7 +254,7 @@ function installFromGit(
     };
   }
 
-  const clone = cloneShallow(source.url);
+  const clone = cloneSource(source);
   if (!clone.ok) return { ok: false, error: clone.error };
   try {
     const stage = source.subpath
@@ -265,6 +274,7 @@ function installFromGit(
       source: source.url,
       ...(source.subpath ? { subpath: source.subpath } : {}),
       ...(clone.commit ? { commit: clone.commit } : {}),
+      ...(source.commit ? { pinned: true } : {}),
     });
     if (clone.commit) {
       console.log(`  ${pc.dim(`Commit ${clone.commit}`)}`);
@@ -338,7 +348,13 @@ async function cmdInstall(args: string[]): Promise<void> {
   }
   const { source, flags } = parsed;
 
-  const resolved = resolveSource(source);
+  const pinned = withCommit(resolveSource(source), flags.commit);
+  if (!pinned.ok) {
+    fail(pinned.error);
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = pinned.source;
   let outcome: EntryOutcome;
   switch (resolved.kind) {
     case "local":

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/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(),
     /**

package/src/core/mesh/credentials/index.ts

@@ -4,7 +4,7 @@
  */
 
 export { DeviceCredentialStore } from "./store.js";
-export { isDeviceCredentialToken } from "./token.js";
+export { credentialIdOf, isDeviceCredentialToken } from "./token.js";
 export {
   DEFAULT_COMPANION_SCOPES,
   FORMER_COMPANION_SCOPES,

package/src/frontend/native/bridge/auth-guard.ts

@@ -5,8 +5,8 @@
  * module decides how a wrong one is answered so an internet-facing bridge
  * can't be hammered for free, and so the operator hears about it.
  *
- * Three layers, all keyed on the remote address (behind a reverse proxy that
- * is the proxy):
+ * Four layers. The first three key on the remote address (behind a reverse
+ * proxy that is the proxy):
  *
  *   1. Progressive backoff: the first few wrong tokens from an address get an
  *      immediate 401; after that each 401 waits longer (base doubling to a
@@ -18,6 +18,14 @@
  *      dodging (1) and (2). The bridge enters a cooldown: wrong tokens get
  *      429 at once, tokenless requests are slowed, the operator is alerted
  *      once. Authenticated traffic keeps working throughout.
+ *   4. Per-credential backoff: a wrong secret presented under a per-device
+ *      credential id (`tdc1.<id>.…` names its id) also counts against that
+ *      id, whatever the address, so guessing one device's credential from
+ *      many addresses backs off as if from one. Backoff only, never a
+ *      lockout: credential ids are safe to log and so knowable, and a
+ *      lockout would let anyone lock a device out. The real credential is
+ *      never delayed, and its successes don't reset the count (they come
+ *      from the device, not from whoever is guessing); the window does.
  *
  * Only presented-and-wrong tokens count as failures. Tokenless probes are
  * scanners finding a locked door. Waits are timers, never a blocked event
@@ -34,8 +42,12 @@ import type { AuthState } from "./routes/table.js";
 export type AuthGuardPolicy = {
   /** Wrong tokens from one address inside the window before 429s. */
   lockoutMaxFailures: number;
+  /** How long an address's (or a credential id's) failures are remembered. */
   lockoutWindowMs: number;
-  /** Hard cap on tracked addresses so the map can't become a memory lever. */
+  /**
+   * Hard cap on tracked addresses, and separately on tracked credential ids,
+   * so neither map can become a memory lever.
+   */
   maxTracked: number;
   /** Wrong tokens answered without delay (typos happen). */
   freeFailures: number;
@@ -77,17 +89,76 @@ export type AuthVerdict =
 
 type Entry = { count: number; resetAt: number };
 
+/**
+ * Failure counts per key (an address or a credential id) inside a window,
+ * capped at `maxTracked` keys.
+ */
+class FailureCounter {
+  private readonly entries = new Map<string, Entry>();
+  private saturatedLogged = false;
+
+  constructor(
+    private readonly what: "address" | "credential",
+    private readonly windowMs: number,
+    private readonly maxTracked: number,
+  ) {}
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  live(key: string, now: number): Entry | undefined {
+    const entry = this.entries.get(key);
+    if (entry && now >= entry.resetAt) {
+      this.entries.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  clear(key: string): void {
+    this.entries.delete(key);
+  }
+
+  /** Bump the key's count; null when the key couldn't be tracked. */
+  record(key: string, now: number): number | null {
+    const entry = this.live(key, now);
+    if (entry) return ++entry.count;
+    if (this.entries.size >= this.maxTracked) {
+      for (const [k, e] of this.entries) {
+        if (now >= e.resetAt) this.entries.delete(k);
+      }
+      // Still saturated after pruning live entries — under that much churn
+      // dropping the newest key beats unbounded growth. The global budget
+      // still counts it.
+      if (this.entries.size >= this.maxTracked) {
+        if (!this.saturatedLogged) {
+          this.saturatedLogged = true;
+          logWarn(
+            "native",
+            `bridge.auth event=tracking_saturated reason=${this.what}_cap tracked=${this.entries.size}`,
+          );
+        }
+        return null;
+      }
+    }
+    this.saturatedLogged = false;
+    this.entries.set(key, { count: 1, resetAt: now + this.windowMs });
+    return 1;
+  }
+}
+
 export class AuthGuard {
   private readonly policy: AuthGuardPolicy;
   private readonly now: () => number;
   private readonly onAlert: ((message: string) => void) | undefined;
-  private readonly failures = new Map<string, Entry>();
+  private readonly failures: FailureCounter;
+  private readonly credentialFailures: FailureCounter;
   private globalCount = 0;
   private globalWindowStart = 0;
   private cooldownUntil = 0;
   private cooling = false;
   private suppressed = 0;
-  private saturatedLogged = false;
   private pending = 0;
 
   constructor(
@@ -97,6 +168,13 @@ export class AuthGuard {
     this.policy = { ...DEFAULT_AUTH_GUARD_POLICY, ...policy };
     this.now = deps.now ?? Date.now;
     this.onAlert = deps.onAlert;
+    const { lockoutWindowMs, maxTracked } = this.policy;
+    this.failures = new FailureCounter("address", lockoutWindowMs, maxTracked);
+    this.credentialFailures = new FailureCounter(
+      "credential",
+      lockoutWindowMs,
+      maxTracked,
+    );
   }
 
   /** Addresses currently tracked (tests and diagnostics). */
@@ -104,6 +182,11 @@ export class AuthGuard {
     return this.failures.size;
   }
 
+  /** Credential ids currently tracked (tests and diagnostics). */
+  trackedCredentialCount(): number {
+    return this.credentialFailures.size;
+  }
+
   /** True while the global failure budget is exhausted. */
   inCooldown(): boolean {
     this.refreshCooldown(this.now());
@@ -112,12 +195,18 @@ export class AuthGuard {
 
   /**
    * Decide how to answer a request whose credential has been evaluated.
-   * Called once per request, before routing.
+   * Called once per request, before routing. `credentialId` is the id a
+   * refused per-device credential named (null for the shared token or
+   * anything malformed) — an identifier, never secret material.
    */
-  check(remote: string, auth: AuthState): AuthVerdict {
+  check(
+    remote: string,
+    auth: AuthState,
+    credentialId: string | null = null,
+  ): AuthVerdict {
     const now = this.now();
     this.refreshCooldown(now);
-    const entry = this.liveEntry(remote, now);
+    const entry = this.failures.live(remote, now);
     if (entry && entry.count >= this.policy.lockoutMaxFailures) {
       return {
         kind: "reject",
@@ -126,7 +215,7 @@ export class AuthGuard {
       };
     }
     if (auth === "ok") {
-      this.failures.delete(remote);
+      this.failures.clear(remote);
       return { kind: "allow" };
     }
     if (auth === "anonymous") {
@@ -134,7 +223,7 @@ export class AuthGuard {
         ? { kind: "delay", ms: this.policy.cooldownAnonDelayMs }
         : { kind: "allow" };
     }
-    return this.fail(remote, now);
+    return this.fail(remote, credentialId, now);
   }
 
   /**
@@ -156,8 +245,16 @@ export class AuthGuard {
 
   // ── internals ────────────────────────────────────────────────────────────
 
-  private fail(remote: string, now: number): AuthVerdict {
-    const count = this.recordFailure(remote, now);
+  private fail(
+    remote: string,
+    credentialId: string | null,
+    now: number,
+  ): AuthVerdict {
+    const count = this.failures.record(remote, now);
+    const credCount =
+      credentialId === null
+        ? null
+        : this.credentialFailures.record(credentialId, now);
     this.recordGlobalFailure(now);
     if (this.cooling) {
       this.suppressed++;
@@ -170,11 +267,15 @@ export class AuthGuard {
         ),
       };
     }
-    const delay = count === null ? 0 : this.backoffFor(count);
+    // Whichever key has seen more failures sets the wait.
+    const delay = Math.max(this.backoffFor(count), this.backoffFor(credCount));
     logWarn(
       "native",
       `bridge.auth event=failure addr=${remote} reason=bad_token` +
         (count === null ? " tracked=no" : ` failures=${count}`) +
+        (credentialId === null
+          ? ""
+          : ` credential=${credentialId} credentialFailures=${credCount ?? "untracked"}`) +
         ` delayMs=${delay}`,
     );
     if (count === this.policy.lockoutMaxFailures) {
@@ -186,7 +287,9 @@ export class AuthGuard {
     return delay > 0 ? { kind: "delay", ms: delay } : { kind: "allow" };
   }
 
-  private backoffFor(count: number): number {
+  /** The wait after the `count`th failure; an untracked key never waits. */
+  private backoffFor(count: number | null): number {
+    if (count === null) return 0;
     const n = count - this.policy.freeFailures;
     if (n <= 0) return 0;
     // 2^(n-1) overflows nothing useful past ~30 doublings; clamp first.
@@ -197,45 +300,6 @@ export class AuthGuard {
     );
   }
 
-  private liveEntry(remote: string, now: number): Entry | undefined {
-    const entry = this.failures.get(remote);
-    if (entry && now >= entry.resetAt) {
-      this.failures.delete(remote);
-      return undefined;
-    }
-    return entry;
-  }
-
-  /** Bump the address's count; null when the address couldn't be tracked. */
-  private recordFailure(remote: string, now: number): number | null {
-    const entry = this.liveEntry(remote, now);
-    if (entry) return ++entry.count;
-    if (this.failures.size >= this.policy.maxTracked) {
-      for (const [ip, e] of this.failures) {
-        if (now >= e.resetAt) this.failures.delete(ip);
-      }
-      // Still saturated after pruning live entries — under that much churn
-      // dropping the newest address beats unbounded growth. The global
-      // budget still counts it.
-      if (this.failures.size >= this.policy.maxTracked) {
-        if (!this.saturatedLogged) {
-          this.saturatedLogged = true;
-          logWarn(
-            "native",
-            `bridge.auth event=tracking_saturated reason=address_cap tracked=${this.failures.size}`,
-          );
-        }
-        return null;
-      }
-    }
-    this.saturatedLogged = false;
-    this.failures.set(remote, {
-      count: 1,
-      resetAt: now + this.policy.lockoutWindowMs,
-    });
-    return 1;
-  }
-
   private recordGlobalFailure(now: number): void {
     if (now - this.globalWindowStart >= this.policy.globalWindowMs) {
       this.globalWindowStart = now;

package/src/frontend/native/bridge/credentials/principal.ts

@@ -17,7 +17,10 @@
  */
 
 import type { IncomingMessage } from "node:http";
-import { isDeviceCredentialToken } from "../../../../core/mesh/credentials/index.js";
+import {
+  credentialIdOf,
+  isDeviceCredentialToken,
+} from "../../../../core/mesh/credentials/index.js";
 import { logWarn } from "../../../../util/log.js";
 
 /**
@@ -137,6 +140,15 @@ function isLocalRequest(req: IncomingMessage): boolean {
   );
 }
 
+/**
+ * The per-device credential id a presented bearer names (`tdc1.<id>.…`), so
+ * a refusal can count against that id as well as the address. Null for the
+ * shared token or anything malformed. Ids are identifiers, safe to log.
+ */
+export function presentedCredentialId(candidate: string): string | null {
+  return credentialIdOf(candidate);
+}
+
 /** Addresses already warned about a refused legacy token (bounded). */
 const refusedLegacy = new Set<string>();
 

package/src/frontend/native/bridge/routes/table.ts

@@ -105,6 +105,19 @@ export const BRIDGE_ROUTE_AUTH = {
 
 export type BridgeRouteKey = keyof typeof BRIDGE_ROUTE_AUTH;
 
+/**
+ * The only routes that take the credential as a `?token=` query parameter.
+ * Everywhere else it must come as `Authorization: Bearer`. A token in a URL
+ * ends up in proxy logs, browser history and screenshots, so it is accepted
+ * only where a client can't set a header: an EventSource stream, and media
+ * handed to an image widget or an external viewer. Those are the only two
+ * places shipped companions put it; talon-node never does.
+ */
+export const QUERY_TOKEN_ROUTES: ReadonlySet<BridgeRouteKey> = new Set([
+  "GET /events",
+  "GET /media",
+]);
+
 /** What a route handler receives; `auth` is already evaluated. */
 export type RouteContext = {
   req: IncomingMessage;

package/src/frontend/native/bridge/server.ts

@@ -45,6 +45,7 @@ import { buildRoutes } from "./routes/index.js";
 import type { BridgeServerHandlers, RouteHost } from "./routes/host.js";
 import {
   BRIDGE_ROUTE_AUTH,
+  QUERY_TOKEN_ROUTES,
   type AuthState,
   type BridgeRouteKey,
   type RouteContext,
@@ -53,6 +54,7 @@ import {
 import {
   describeTier,
   hasScope,
+  presentedCredentialId,
   resolvePrincipal,
   routeAllows,
   type BridgeCredentials,
@@ -519,10 +521,14 @@ export class BridgeServer {
     }
 
     const remote = req.socket.remoteAddress ?? "unknown";
-    const { state: auth, principal } = this.authState(req, url);
-    if (!(await this.admit(res, remote, auth))) return;
-
     const key = `${method} ${path}` as BridgeRouteKey;
+    const {
+      state: auth,
+      principal,
+      credentialId,
+    } = this.authState(req, url, QUERY_TOKEN_ROUTES.has(key));
+    if (!(await this.admit(res, remote, auth, credentialId))) return;
+
     const route = this.routes.get(key);
     const ctx: RouteContext = { req, res, url, auth, principal };
     const tier = route ? BRIDGE_ROUTE_AUTH[key] : undefined;
@@ -706,19 +712,34 @@ export class BridgeServer {
 
   // ── Helpers ──────────────────────────────────────────────────────────────
 
+  /**
+   * Evaluate the presented credential. `queryToken` says whether this route
+   * also takes it as `?token=` (QUERY_TOKEN_ROUTES); elsewhere a query
+   * token is ignored, so the request reads as tokenless. A refused
+   * per-device credential reports the id it named, for the auth guard.
+   */
   private authState(
     req: IncomingMessage,
     url: URL,
-  ): { state: AuthState; principal: BridgePrincipal | null } {
-    if (!this.opts.token) return { state: "ok", principal: { kind: "open" } };
+    queryToken: boolean,
+  ): {
+    state: AuthState;
+    principal: BridgePrincipal | null;
+    credentialId: string | null;
+  } {
+    if (!this.opts.token) {
+      return { state: "ok", principal: { kind: "open" }, credentialId: null };
+    }
     const header = req.headers["authorization"];
     const fromHeader =
       typeof header === "string" && header.startsWith("Bearer ")
         ? header.slice("Bearer ".length)
         : null;
-    // EventSource can't set headers, so SSE clients pass ?token=… instead.
-    const candidate = fromHeader ?? url.searchParams.get("token");
-    if (candidate === null) return { state: "anonymous", principal: null };
+    const candidate =
+      fromHeader ?? (queryToken ? url.searchParams.get("token") : null);
+    if (candidate === null) {
+      return { state: "anonymous", principal: null, credentialId: null };
+    }
     // The shared token or a per-device credential (credentials/principal.ts).
     const principal = resolvePrincipal(
       candidate,
@@ -727,8 +748,12 @@ export class BridgeServer {
       this.opts.credentials,
     );
     return principal
-      ? { state: "ok", principal }
-      : { state: "bad", principal: null };
+      ? { state: "ok", principal, credentialId: null }
+      : {
+          state: "bad",
+          principal: null,
+          credentialId: presentedCredentialId(candidate),
+        };
   }
 
   /**
@@ -740,8 +765,9 @@ export class BridgeServer {
     res: ServerResponse,
     remote: string,
     auth: AuthState,
+    credentialId: string | null,
   ): Promise<boolean> {
-    const verdict = this.authGuard.check(remote, auth);
+    const verdict = this.authGuard.check(remote, auth, credentialId);
     if (verdict.kind === "reject") {
       this.refuse(
         res,

package/src/storage/skills.ts

@@ -62,6 +62,11 @@ const SKILL_FILE = "SKILL.md";
  * sibling file survives every update, and is visible in the filesystem.
  */
 const DISABLED_FILE = ".disabled";
+/**
+ * Provenance `talon skill install` writes for a cloned source (repo URL,
+ * commit) — metadata, not a resource the skill offers.
+ */
+const INSTALL_RECORD_FILE = ".talon-install.json";
 const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 const DESCRIPTION_MAX_CHARS = 300;
 const BODY_MAX_BYTES = 128 * 1024;
@@ -212,7 +217,8 @@ function listResources(dir: string): string[] {
         (entry) =>
           entry.isFile() &&
           entry.name !== SKILL_FILE &&
-          entry.name !== DISABLED_FILE,
+          entry.name !== DISABLED_FILE &&
+          entry.name !== INSTALL_RECORD_FILE,
       )
       .map((entry) => entry.name)
       .sort((a, b) => a.localeCompare(b));