skillrepo 4.8.3 → 4.9.0

package/README.md

@@ -370,7 +370,7 @@ By default `skillrepo init` prompts you to install this hook. If you said no (or
 
 #### Auto-refresh hooks for other agents
 
-For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library refreshes on every session start without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
+For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library stays current across your sessions without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
 
 | Agent | Hook config path | Notes |
 |-------|------------------|-------|
@@ -393,6 +393,8 @@ Auto-refresh hooks for Windsurf and Cline are not yet supported — those agents
 
 **On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
 
+**Throttled to skip redundant syncs (v4.9.0+).** Because the hook fires on *every* editor session, the hook-triggered `update` (`--session-hook` / `--silent`) syncs at most once per ~15 minutes: within that window it exits immediately with **no network call**. This bounds redundant per-session load. The tradeoff is that a brand-new session started shortly after a recent sync may be up to ~15 minutes behind a just-published change — and the same bound applies to local repair: if you delete or corrupt a synced skill's folder on disk, the hook restores it on its next non-throttled run, up to ~15 minutes later. A bare `skillrepo update` **you** run yourself is never throttled — it always syncs immediately (repairing any local damage) and resets the window. `skillrepo list` is likewise never throttled (it always queries the server live), though it doesn't reset the window.
+
 Flags:
 
 - `--global` — operates on `~/.claude/settings.local.json` so the hook fires in every Claude Code session across all projects on your machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.8.3",
+  "version": "4.9.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/update.mjs

@@ -20,6 +20,10 @@
  *                    full contract. When this flag is absent, the
  *                    command behaves as before (exit non-zero on
  *                    network / auth / disk failures).
+ *                    Throttled (#2174): within MIN_SYNC_INTERVAL_MS of the
+ *                    last sync attempt this makes ZERO network calls (the
+ *                    hook fires every session; a bare `update` is never
+ *                    throttled).
  *
  * v4.1.0 silent mode (#1240):
  *   --silent         Suppress stdout: write `{}` on success, propagate
@@ -144,6 +148,11 @@ export async function runUpdate(argv, io = {}) {
         apiKey: flags.apiKey,
         vendors,
         global: flags.global,
+        // Throttle SessionStart syncs (#2174): this hook fires on every
+        // Claude Code session, so within MIN_SYNC_INTERVAL_MS of the last
+        // attempt runSync short-circuits with zero network calls. ONLY hook
+        // invocations pass this — a bare `skillrepo update` always syncs.
+        throttle: true,
         io: { stdout: BLACK_HOLE_STREAM, stderr: BLACK_HOLE_STREAM },
       });
       const total = summary.added + summary.updated + summary.removed;
@@ -218,6 +227,10 @@ export async function runUpdate(argv, io = {}) {
       apiKey: flags.apiKey,
       vendors,
       global: flags.global,
+      // Throttle the cohort SessionStart hook too (#2174) — same reasoning
+      // as --session-hook: it fires every session, so skip the network
+      // within MIN_SYNC_INTERVAL_MS of the last attempt.
+      throttle: true,
       // sync.mjs surfaces non-fatal warnings (e.g. failed to persist
       // last-sync state) via stderr; preserve that channel so a real
       // operator running `update --silent` from a terminal can still

package/src/lib/http.mjs

@@ -370,6 +370,25 @@ async function mapErrorResponse(res, url) {
   if (res.status === 404) {
     return null; // Caller decides
   }
+  if (res.status === 422 && code === "handle_required") {
+    // #2310: the push would CREATE a skill while the account's Author ID
+    // is still an unchosen placeholder. Line 1 is the server's message
+    // ("Set your Author ID before adding skills."); the hint points at
+    // the Settings surface that unblocks it. Derive the base URL from
+    // the request URL's origin (same posture as the 401 auth hint above)
+    // so staging users get a staging link, with the prod host as the
+    // parse-failure fallback.
+    let settingsBase = "https://skillrepo.dev";
+    try {
+      settingsBase = new URL(url).origin;
+    } catch {
+      // URL parse failure shouldn't happen — `safeFetch` already
+      // validated. Fall back to the prod default.
+    }
+    return validationError(message, {
+      hint: `Set it in Settings → Account Profile: ${settingsBase}/app/settings`,
+    });
+  }
   if (res.status === 429) {
     // 429 hits mapErrorResponse in two cases: (1) a read-only
     // endpoint's retry budget was exhausted (safeFetch with

package/src/lib/sync.mjs

@@ -36,20 +36,34 @@
  *        absence is meaningful (a state file with no `cliVersion` was
  *        written by a pre-#1911 CLI and triggers the one-time membership
  *        heal). See `FULL_RESYNC_FLOOR` / `cliVersionBelowFloor`.
+ *   v3 — Adds `lastAttemptAt` (#2174): an ISO timestamp of the last
+ *        network sync ATTEMPT, powering the SessionStart staleness
+ *        throttle in `runSync`. Stamped on the 304 short-circuit and on
+ *        every successful write; NOT stamped on a throttled skip (so a
+ *        run of quick restarts can't push the clock forward and starve
+ *        the sync). A v2 file (no `lastAttemptAt`) reads as "never
+ *        attempted" and syncs — additive, mirroring how absent
+ *        `cliVersion` was handled.
  *
  * Forward/backward compatibility
  * ------------------------------
- *   • Old CLI reading a v2 file → unknown schemaVersion → null → full
- *     sync → writes v1 file. User loses per-skill metadata until they
- *     upgrade again.
- *   • New CLI reading a v1 file → in-memory migration to a v2 shape
- *     with the existing `etag` + `syncedAt` preserved and an EMPTY
- *     `skills` map. The next successful sync writes a v2 file on
- *     disk. This is safe because an empty map means "we don't know
+ *   • Old CLI reading a NEWER file (e.g. a v2 CLI reading v3) → unknown
+ *     schemaVersion → null → full sync → writes its own older shape. The
+ *     user loses the newer fields until they upgrade again. Harmless: a
+ *     full re-fetch is idempotent.
+ *   • New CLI reading a v1 file → in-memory migration to the current
+ *     shape with the existing `etag` + `syncedAt` preserved and an EMPTY
+ *     `skills` map. The next successful sync writes a current-schema file
+ *     on disk. This is safe because an empty map means "we don't know
  *     per-skill state from this sync" — callers must treat absent
  *     entries as unknown, not as "missing from library." Preserving
  *     the etag also keeps the 304 short-circuit working, so an
  *     upgrade-then-no-changes path stays cheap.
+ *   • New CLI reading a v2 file → accepted in place (v2 is v3 minus
+ *     `lastAttemptAt`): etag/syncedAt/skills/cliVersion are preserved so
+ *     the first post-upgrade sync stays a cheap 304, and the absent
+ *     `lastAttemptAt` makes the throttle treat it as "never attempted"
+ *     so that first sync proceeds and then stamps a v3 file.
  *   • Future unknown schemaVersion → null → full sync. Forward-compat
  *     without crashing.
  *
@@ -58,6 +72,18 @@
  * @property {number} updated     - Skills overwritten on disk
  * @property {number} removed     - Tombstones applied
  * @property {boolean} notModified - True if 304 short-circuit fired
+ * @property {boolean} [throttled] - True when the SessionStart staleness
+ *                                   throttle skipped this run entirely — no
+ *                                   library GET, no receipt POST (#2174).
+ *                                   Only set on the throttled early-exit;
+ *                                   absent (falsy) on every other path.
+ *                                   NOTE: no production caller branches on
+ *                                   this today (hook printers key on the
+ *                                   zero counters) — it is the contract
+ *                                   discriminator that lets tests tell a
+ *                                   throttled skip from a 304, mirroring
+ *                                   the `minSyncIntervalMs` test-seam
+ *                                   pattern.
  * @property {boolean | null} fullSync - True if this was a full (non-delta)
  *                                   sync — i.e. no prior `.last-sync` state
  *                                   existed so no `since` was sent. False if
@@ -73,7 +99,6 @@
  *                                   Consumers must distinguish these to
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
- * @property {string} [syncedAt]
  * @property {string} syncedAt    - ISO timestamp of the sync: the server
  *                                   response `syncedAt` on a 200, or the
  *                                   previously-cached sync timestamp on a
@@ -97,6 +122,10 @@
  *                                   wrote this state. Absent on files written
  *                                   by a pre-#1911 CLI; absence triggers the
  *                                   one-time membership heal.
+ * @property {string} [lastAttemptAt] - v3+ (#2174). ISO timestamp of the last
+ *                                   network sync attempt. Absent on a v2 file
+ *                                   (or any pre-v3 writer) → the throttle
+ *                                   treats it as "never attempted" and syncs.
  * @property {Record<string, SyncedSkillEntry>} skills - v2+. Keyed by `"<owner>/<name>"`.
  */
 
@@ -127,8 +156,49 @@ import { computeSkillShas } from "./crypto-shas.mjs";
  *
  * v2 (#1553): adds `skills` map keyed by `"<owner>/<name>"` →
  * `{ version, skillMdSha256, filesSha256, syncedAt }`.
+ * v3 (#2174): adds `lastAttemptAt` — an ISO timestamp of the last
+ * network sync ATTEMPT (stamped on the 304 short-circuit and on every
+ * successful write, NOT on a throttled skip). Powers the SessionStart
+ * staleness throttle. Additive: a v2 file (no `lastAttemptAt`) reads as
+ * "never attempted" and syncs, so the bump is forward-compatible and a
+ * v2 file is accepted in place — its etag/skills are preserved (no
+ * forced re-fetch, unlike the v1→v2 migration).
  */
-export const LAST_SYNC_SCHEMA_VERSION = 2;
+export const LAST_SYNC_SCHEMA_VERSION = 3;
+
+/**
+ * Client-side SessionStart sync throttle window (#2174).
+ *
+ * A hook-triggered `skillrepo update` (the `--session-hook` and
+ * `--silent` cohort hooks) skips the network entirely — NO library GET,
+ * NO sync-receipt POST — when the last sync ATTEMPT was less than this
+ * long ago. This caps the highest-QPS uncacheable vector: the library
+ * sync fires on every editor session, and at 100k users the per-request
+ * cost (auth + rate-limit + per-account ETag query + heartbeat, then a
+ * second request for the receipt) dominates even on a 304. See #2170.
+ *
+ * SCOPE: hook invocations ONLY. A bare interactive `skillrepo update`
+ * always syncs (explicit intent), and it too stamps `lastAttemptAt`, so
+ * a manual sync resets the window for subsequent hook syncs.
+ *
+ * FRESHNESS: this bounds how stale a hook-skipped session can be to at
+ * most this window, measured from the last ACTUAL sync — NOT from a
+ * publish time, and NOT between raw session starts (a skipped session
+ * does not advance the clock, so continuous restarts can't starve the
+ * sync). Sessions spaced further apart than this window always sync.
+ * The SAME bound applies to LOCAL damage, not just server-side changes:
+ * a throttled skip returns before the placement-presence check below,
+ * so a skill directory the user deleted/corrupted on disk is repaired
+ * on the next non-throttled sync — up to this window later, or
+ * immediately via an interactive `update` (never throttled). Pre-#2174
+ * every session start repaired placements immediately; "my skill
+ * briefly disappeared after I deleted its folder" within this window
+ * is expected behavior, not a placement-check bug.
+ *
+ * 15 minutes (#2174, product-confirmed). Override per-call via
+ * `runSync({ minSyncIntervalMs })` — a test seam used to pin the boundary.
+ */
+export const MIN_SYNC_INTERVAL_MS = 15 * 60 * 1000;
 
 /**
  * One-time heal floor (#1911).
@@ -317,11 +387,12 @@ export function readLastSync() {
     return null;
   }
 
-  // v1 → v2 in-memory migration. Preserve the etag and syncedAt so
-  // delta sync still benefits from the prior state; start with an
-  // empty `skills` map. The next successful runSync writes v2 to
-  // disk. We do NOT write here — readers should be pure with
-  // respect to the filesystem.
+  // v1 → current-schema in-memory migration. Preserve the etag and
+  // syncedAt so delta sync still benefits from the prior state; start
+  // with an empty `skills` map (and no `lastAttemptAt`, so the throttle
+  // treats this as "never attempted"). The next successful runSync
+  // writes the current schema to disk. We do NOT write here — readers
+  // should be pure with respect to the filesystem.
   if (parsed.schemaVersion === 1) {
     return {
       schemaVersion: LAST_SYNC_SCHEMA_VERSION,
@@ -331,7 +402,24 @@ export function readLastSync() {
     };
   }
 
-  if (parsed.schemaVersion !== LAST_SYNC_SCHEMA_VERSION) {
+  // Accept the current schema AND the immediately-prior v2 (which is v3
+  // minus `lastAttemptAt`, #2174). A v2 file is read IN PLACE — its
+  // etag/syncedAt/skills/cliVersion are preserved, so the first
+  // post-upgrade sync stays a cheap 304 rather than a forced re-fetch;
+  // the absent `lastAttemptAt` makes the throttle treat it as "never
+  // attempted" so that first sync still proceeds, then writes a v3 file.
+  // Any OTHER version (v1 is migrated above; a future v4+ is unknown) →
+  // null → full sync. Forward-compat without crashing.
+  //
+  // MAINTAINER: the `!== 2` literal is the "accept the immediately-prior
+  // schema in place" branch — it is NOT auto-derived from
+  // LAST_SYNC_SCHEMA_VERSION. The next bump (v3 → v4) must add its own
+  // `!== 3` branch here (accept v3 in place; v2 then falls through to a
+  // full sync), the same way this branch was added for v2 → v3.
+  if (
+    parsed.schemaVersion !== LAST_SYNC_SCHEMA_VERSION &&
+    parsed.schemaVersion !== 2
+  ) {
     return null;
   }
 
@@ -351,6 +439,16 @@ export function readLastSync() {
     parsed.skills = {};
   }
 
+  // `lastAttemptAt` (v3+, #2174) must be an ISO string to be usable by
+  // the throttle. A v2 file omits it; a malformed value (number, object,
+  // truncated write) is coerced to absent so the throttle treats the
+  // state as "never attempted" and syncs rather than trusting a bogus
+  // clock. `Date.parse` in runSync is a second guard, but normalizing
+  // here keeps the returned shape honest for every caller.
+  if (typeof parsed.lastAttemptAt !== "string") {
+    delete parsed.lastAttemptAt;
+  }
+
   return parsed;
 }
 
@@ -375,19 +473,31 @@ export function readLastSync() {
  * never re-healed. A caller-supplied `cliVersion` overrides the stamp (used
  * only by tests to simulate a pre-fix writer); production callers omit it.
  *
+ * v3 (#2174): `lastAttemptAt` is the ISO timestamp of the last network
+ * sync attempt, used by the throttle. It is NOT auto-stamped: callers pass
+ * it explicitly so intent is unambiguous. `runSync` passes "now" on the 304
+ * and successful-write paths; the single-skill helpers (`upsertLastSyncEntry`
+ * / `deleteLastSyncEntry`) preserve the prior value verbatim because a
+ * single-skill add/remove is not a full-library sync and must not advance
+ * the throttle clock. Omitting it persists `null` — an explicit "never
+ * attempted" that never wrongly throttles the next sync.
+ *
  * @param {object} state
  * @param {string | null} [state.etag]
  * @param {string} [state.syncedAt]
  * @param {Record<string, SyncedSkillEntry>} [state.skills]
  * @param {string | null} [state.cliVersion] - Override the writer-version
  *        stamp. Defaults to the running CLI's version.
+ * @param {string | null} [state.lastAttemptAt] - ISO timestamp of the last
+ *        sync attempt (#2174). Omitting it persists `null`.
  */
-export function writeLastSync({ etag, syncedAt, skills, cliVersion } = {}) {
+export function writeLastSync({ etag, syncedAt, skills, cliVersion, lastAttemptAt } = {}) {
   const path = globalLastSyncPath();
   const body = {
     schemaVersion: LAST_SYNC_SCHEMA_VERSION,
     etag: etag ?? null,
     syncedAt: syncedAt ?? new Date().toISOString(),
+    lastAttemptAt: lastAttemptAt ?? null,
     cliVersion: cliVersion !== undefined ? cliVersion : safeCliVersion(),
     skills: skills && typeof skills === "object" && !Array.isArray(skills) ? skills : {},
   };
@@ -480,6 +590,11 @@ export function upsertLastSyncEntry(skill) {
     // carries a pre-fix file's absent version forward as an explicit null
     // so the next `update` still heals. Same rationale as etag/syncedAt.
     cliVersion: prior?.cliVersion ?? null,
+    // Preserve the throttle clock (#2174) — a single-skill `add`/`get` is
+    // not a full-library sync, so it must NOT advance `lastAttemptAt` (that
+    // would wrongly throttle the next SessionStart sync). Same rationale as
+    // cliVersion above.
+    lastAttemptAt: prior?.lastAttemptAt ?? null,
   });
 }
 
@@ -507,6 +622,9 @@ export function deleteLastSyncEntry(owner, name) {
     // reconciliation, so it must not advance the one-time heal gate.
     // See upsertLastSyncEntry for the full rationale.
     cliVersion: prior.cliVersion ?? null,
+    // Preserve the throttle clock (#2174) — `remove` is not a full sync,
+    // so it must not advance `lastAttemptAt`. Same rationale as cliVersion.
+    lastAttemptAt: prior.lastAttemptAt ?? null,
   });
 }
 
@@ -514,12 +632,16 @@ export function deleteLastSyncEntry(owner, name) {
  * Run a library sync against the server.
  *
  * Strategy:
- *   1. Clean up any orphan .tmp/.old directories from a crashed prior run
- *   2. Read the last-sync state file
+ *   1. Read the last-sync state, then apply the SessionStart throttle
+ *      (#2174): a hook-triggered sync (`throttle: true`) within
+ *      MIN_SYNC_INTERVAL_MS of the last attempt short-circuits HERE with
+ *      ZERO network calls. A bare interactive `update` never throttles.
+ *   2. Clean up any orphan .tmp/.old directories from a crashed prior run
  *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
  *      cached ETag) AND `since` (always, for delta semantics)
  *   4. On 304 — re-assert the on-disk state via a receipt (liveness +
- *      heal) and short-circuit with `notModified: true`
+ *      heal), stamp the throttle clock (`lastAttemptAt`), and short-circuit
+ *      with `notModified: true`
  *   5. For each skill in the response:
  *      a. Write it via `writeSkillDir` — overwrites if changed
  *      b. Skip writing skills with `filesIncomplete: true` (see comment)
@@ -546,10 +668,20 @@ export function deleteLastSyncEntry(owner, name) {
  *                  when `writeLastSync` fails uses io.stderr so tests that
  *                  inject a capture stream don't lose that output.
  * @param {NodeJS.WritableStream} [options.io.stderr=process.stderr]
+ * @param {boolean} [options.throttle] - Hook-triggered syncs ONLY
+ *                  (update.mjs's --session-hook / --silent branches) pass
+ *                  true. When the last attempt was within the interval, the
+ *                  whole sync short-circuits with zero network calls and a
+ *                  `throttled: true` summary (#2174). A bare interactive
+ *                  `skillrepo update` omits this and always syncs.
+ * @param {number} [options.minSyncIntervalMs] - Override the throttle window
+ *                  (defaults to MIN_SYNC_INTERVAL_MS). A test seam to pin the
+ *                  boundary; production callers omit it.
  * @returns {Promise<SyncSummary>}
  */
 export async function runSync(options) {
-  const { serverUrl, apiKey, vendors, global, io } = options;
+  const { serverUrl, apiKey, vendors, global, io, throttle, minSyncIntervalMs } =
+    options;
   // Coalesce both `undefined` AND `null` to {}. Destructuring with
   // `io = {}` only handles `undefined`, so an explicit `io: null`
   // would otherwise blow up at the .stderr access below. Both
@@ -564,12 +696,70 @@ export async function runSync(options) {
     throw validationError("runSync: apiKey is required");
   }
 
-  // Step 1: clean orphans from prior crashes BEFORE doing any new writes
-  cleanupOrphans({ vendors, global });
-
-  // Step 2: read prior state
+  // Read prior state FIRST — the throttle decision below needs it, and
+  // reading one small JSON file is far cheaper than the orphan scan.
+  // Reordered ahead of cleanupOrphans (#2174) so a throttled hook sync
+  // does no filesystem walking either.
   const lastSync = readLastSync();
 
+  // SessionStart staleness throttle (#2174). Hook-triggered syncs
+  // (`throttle: true`, set ONLY by update.mjs's --session-hook and
+  // --silent branches) skip ALL network work — no library GET, no receipt
+  // POST — when the last ATTEMPT was within the interval. A bare
+  // interactive `skillrepo update` passes no `throttle`, so it always
+  // syncs (explicit intent). `lastAttemptAt` is absent on a fresh install
+  // and on a v2 file (never attempted) → those never throttle. A skipped
+  // run does NOT re-stamp `lastAttemptAt` (only an actual sync does), so
+  // continuous restarts can't push the clock forward and starve the sync:
+  // the window is measured from the last REAL sync, not the last session.
+  const intervalMs =
+    typeof minSyncIntervalMs === "number" && minSyncIntervalMs >= 0
+      ? minSyncIntervalMs
+      : MIN_SYNC_INTERVAL_MS;
+  if (throttle && lastSync && typeof lastSync.lastAttemptAt === "string") {
+    const lastAttemptMs = Date.parse(lastSync.lastAttemptAt);
+    const now = Date.now();
+    const sinceLastAttemptMs = now - lastAttemptMs;
+    // Guard BOTH ends of the window. A FUTURE `lastAttemptAt` (negative
+    // delta — backward clock jump, VM snapshot restore, hand-edited or
+    // corrupt state file) must SYNC, not throttle: a plain `< intervalMs`
+    // check stays true until the wall clock catches up to the bogus
+    // stamp, silently disabling the hook sync for that whole span (hook
+    // modes are contract-silent, so the user would never see it).
+    // Syncing instead re-stamps a sane "now" — one pass self-heals.
+    if (
+      Number.isFinite(lastAttemptMs) &&
+      sinceLastAttemptMs >= 0 &&
+      sinceLastAttemptMs < intervalMs
+    ) {
+      // SKILLREPO_VERBOSE gives the acceptance check a human-observable
+      // signal alongside the request-count spy — one dim stderr line only;
+      // stdout stays clean for the hook contracts.
+      if (process.env.SKILLREPO_VERBOSE) {
+        const agoS = Math.round(sinceLastAttemptMs / 1000);
+        const winS = Math.round(intervalMs / 1000);
+        stderr.write(
+          `  [skillrepo] sync throttled: last attempt ${agoS}s ago < ${winS}s window; skipping network.\n`,
+        );
+      }
+      return {
+        added: 0,
+        updated: 0,
+        removed: 0,
+        notModified: false,
+        throttled: true,
+        // Prior state existed (we had a lastAttemptAt) → never a first
+        // sync. Surface the cached syncedAt so consumers that read it
+        // (e.g. init.mjs) see the last known-good sync time.
+        fullSync: false,
+        syncedAt: lastSync.syncedAt ?? new Date(now).toISOString(),
+      };
+    }
+  }
+
+  // Step 2: clean orphans from prior crashes BEFORE doing any new writes
+  cleanupOrphans({ vendors, global });
+
   // Step 3: fetch with conditional headers
   const opts = {};
   // The ETag short-circuit is only safe when EVERY skill in
@@ -638,6 +828,20 @@ export async function runSync(options) {
   // 4.8.0 heal, its `writeLastSync` re-emits a file with no `cliVersion`, so
   // the next 4.8.0 run heals again. That loop is harmless — a full re-fetch
   // is idempotent — and self-resolves once the older install is upgraded.
+  //
+  // Same-machine SPLIT-FLEET churn (#2174 rollout, tracked via #2181): the
+  // cohort hooks run `npx --yes skillrepo update --silent` (npm `latest` on
+  // every session), while the Claude Code hook pins the globally-installed
+  // binary. Until that global install is upgraded past the v3 schema bump,
+  // the two alternate writers ping-pong `.last-sync`: the ≥4.9.0 npx run
+  // writes schemaVersion 3; the ≤4.8.x pinned binary doesn't recognize v3 →
+  // null → FULL non-conditional fetch → writes v2 back (dropping
+  // `lastAttemptAt`), and the next npx run re-upgrades. Consequences while
+  // the split persists: the pinned binary never gets a 304 short-circuit
+  // and the throttle keeps getting disarmed — bounded by the once-daily
+  // upgrade nudge (bin/skillrepo.mjs), self-resolving on `npm install -g
+  // skillrepo@latest`. Harmless to data (full re-fetch is idempotent);
+  // do NOT add a compat shim for it here.
   const needsFullResync =
     !!lastSync && cliVersionBelowFloor(lastSync.cliVersion, FULL_RESYNC_FLOOR);
 
@@ -679,6 +883,31 @@ export async function runSync(options) {
       new Date().toISOString(),
       stderr,
     );
+
+    // Stamp the throttle clock (#2174). LOAD-BEARING: a deliberately-
+    // stable library is a 304 on every session, so if we didn't advance
+    // `lastAttemptAt` here the throttle would never re-arm and every future
+    // hook sync would hit the network again — defeating the whole feature.
+    // Preserve etag/syncedAt/skills verbatim (the library is unchanged; only
+    // the attempt clock moves) and preserve cliVersion — a 304 is NOT a
+    // membership heal, and reaching a 304 already implies we sent
+    // If-None-Match, i.e. cliVersion was >= the heal floor. Best-effort: a
+    // failed stamp just means the next hook sync isn't throttled, never a
+    // sync failure.
+    try {
+      writeLastSync({
+        etag: lastSync?.etag ?? null,
+        syncedAt: lastSync?.syncedAt,
+        skills: lastSync?.skills ?? {},
+        cliVersion: lastSync?.cliVersion ?? null,
+        lastAttemptAt: new Date().toISOString(),
+      });
+    } catch (err) {
+      stderr.write(
+        `  warning: failed to persist last-sync state (${err.message}). ` +
+          `Next sync will not be throttled.\n`,
+      );
+    }
     return {
       added: 0,
       updated: 0,
@@ -827,6 +1056,11 @@ export async function runSync(options) {
         etag: result.etag,
         syncedAt: result.syncedAt,
         skills: skillsMap,
+        // Stamp the throttle clock on every successful sync (#2174). Gated
+        // by the same `!anyIncomplete` guard as the ETag: a partial payload
+        // does NOT advance the clock, so a broken sync is retried on the
+        // next session rather than throttled away.
+        lastAttemptAt: new Date().toISOString(),
       });
     } catch (err) {
       // Non-fatal — the skills are on disk, we just won't get the

package/src/test/commands/publish.test.mjs

@@ -220,7 +220,7 @@ describe("runPublish — error paths", () => {
     server.setPublishResponse("alice", "my-skill", {
       status: 422,
       body: {
-        error: "Choose your Author ID before publishing.",
+        error: "Set your Author ID before publishing.",
         code: "namespace_unset",
       },
     });

package/src/test/commands/push.test.mjs

@@ -453,6 +453,30 @@ describe("runPush — server error mapping", () => {
     );
   });
 
+  it("maps server 422 handle_required to EXIT_VALIDATION with the Settings hint (#2310, #2345)", async () => {
+    // The dedicated #2310 branch in mapErrorResponse: friendly message
+    // plus the Settings pointer. Previously pinned only at the
+    // http.test.mjs layer against hand-built JSON — this runs the whole
+    // runPush chain against the same wire shape the server emits
+    // (route.ts:724: `{ error, code: "handle_required" }`).
+    file("SKILL.md", VALID_SKILL_MD);
+    server.setPushResponse({
+      status: 422,
+      body: {
+        error: "Set your Author ID before adding skills.",
+        code: "handle_required",
+      },
+    });
+    await assert.rejects(
+      runPush(["--key", VALID_KEY, "--url", serverUrl, "skill"], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /author id/i.test(err.message) &&
+        /settings/i.test(err.hint ?? ""),
+    );
+  });
+
   it("maps server 413 payload_too_large to EXIT_VALIDATION (generic 4xx)", async () => {
     // 413 has NO explicit branch in mapErrorResponse (only 401/403/404/
     // 429/5xx are special-cased). It therefore falls through to the