skillrepo 4.8.4 → 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.4",
+  "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/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/update.test.mjs

@@ -18,7 +18,9 @@ import {
   writeLastSync,
   FULL_RESYNC_FLOOR,
   cliVersionBelowFloor,
+  LAST_SYNC_SCHEMA_VERSION,
 } from "../../lib/sync.mjs";
+import { globalLastSyncPath } from "../../lib/paths.mjs";
 import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
@@ -689,3 +691,167 @@ describe("runUpdate — #1911 membership heal lands the skill on disk", () => {
     );
   });
 });
+
+// ── SessionStart throttle through the `update` command (#2174) ─────────
+//
+// The throttle lives in runSync, but what matters at the product boundary
+// is that `skillrepo update --session-hook` (Claude Code) and the
+// `--silent` cohort hook make ZERO HTTP calls when re-run within the
+// window, while a bare interactive `skillrepo update` always syncs. These
+// drive the real command entry point against the mock server's request
+// spies — the acceptance criterion, end to end.
+
+describe("runUpdate — SessionStart throttle (#2174)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("ACCEPTANCE: two `update --session-hook` runs within the window → the 2nd makes zero HTTP calls", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("throttle-me")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // Session 1: the hook runs a real sync (no prior attempt).
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.ok(server.getLibraryRequestCount() >= 1, "session 1 hit the library GET");
+    assert.match(stdout.text(), /Library synced/, "session 1 reports the sync");
+
+    // Session 2 (same 15-min window): the hook must make NO HTTP calls.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+
+    assert.equal(
+      server.getLibraryRequestCount(),
+      0,
+      "throttled session makes NO library GET",
+    );
+    assert.equal(
+      server.getReceiptRequestCount(),
+      0,
+      "throttled session makes NO receipt POST",
+    );
+    assert.equal(
+      stdout.text(),
+      "",
+      "throttled session-hook stays silent (nothing changed to report)",
+    );
+  });
+
+  it("a bare interactive `skillrepo update` always syncs, even seconds after a hook sync", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("fresh")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Hook sync arms the throttle clock.
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    // Interactive `update` (no hook flag) must contact the server despite
+    // the fresh clock — explicit intent always syncs.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "interactive update is never throttled",
+    );
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "interactive 304 prints the up-to-date line",
+    );
+  });
+
+  it("the --silent cohort hook throttles too (2nd run: zero HTTP, still emits `{}`)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("cohort")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--silent"], { stdout });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--silent"], { stdout });
+    assert.equal(
+      server.getLibraryRequestCount(),
+      0,
+      "throttled --silent makes NO library GET",
+    );
+    assert.equal(
+      server.getReceiptRequestCount(),
+      0,
+      "throttled --silent makes NO receipt POST",
+    );
+    // The JSON hook contract still holds: stdout is exactly `{}` even when
+    // the sync was throttled away.
+    assert.equal(stdout.text(), "{}\n");
+  });
+
+  it("upgrade path: a real v2 .last-sync (etag + skills, no lastAttemptAt) → first hook sync proceeds and upgrades to v3", async () => {
+    // Every existing install upgrading to 4.9.0 hits exactly this state:
+    // a v2 file with a genuine etag/skills baseline written by the old
+    // CLI. The first --session-hook run after upgrade must NOT throttle
+    // (no lastAttemptAt = never attempted), must keep the cheap 304 (etag
+    // preserved in place), and must leave a v3 file with the stamp.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("veteran")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Arm a fully-populated state via a real sync, then rewrite it as the
+    // v2 shape a pre-#2174 CLI would have left behind.
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    const prior = readLastSync();
+    const v2File = {
+      schemaVersion: 2,
+      etag: prior.etag,
+      syncedAt: prior.syncedAt,
+      cliVersion: prior.cliVersion,
+      skills: prior.skills,
+    };
+    writeFileSync(globalLastSyncPath(), JSON.stringify(v2File, null, 2) + "\n");
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "first post-upgrade hook sync is NOT throttled (v2 = never attempted)",
+    );
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      prior.etag,
+      "the v2 etag was accepted in place — the post-upgrade sync stays a cheap 304",
+    );
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION, "file upgraded to v3");
+    assert.equal(typeof after.lastAttemptAt, "string", "throttle clock stamped");
+    assert.deepEqual(after.skills, prior.skills, "per-skill SHA baseline preserved");
+  });
+});

package/src/test/integration/update-list-contract.integration.test.mjs

@@ -57,7 +57,7 @@ import { runAdd } from "../../commands/add.mjs";
 import { runRemove } from "../../commands/remove.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
-import { readLastSync } from "../../lib/sync.mjs";
+import { readLastSync, LAST_SYNC_SCHEMA_VERSION } from "../../lib/sync.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
 import {
@@ -391,11 +391,11 @@ describe("update → list cross-command contract (#1574)", () => {
 // is the only way to verify the v2 file that lands on disk has the
 // expected shape AND the ETag carry-forward took effect.
 
-describe("v1 → v2 .last-sync migration round-trip", () => {
+describe("v1 → current-schema .last-sync migration round-trip", () => {
   beforeEach(setup);
   afterEach(teardown);
 
-  it("reads v1 .last-sync, performs sync, writes v2 with SHA map populated", async () => {
+  it("reads v1 .last-sync, performs sync, writes the current schema with SHA map populated", async () => {
     // Seed a v1 state file at the documented path. Both fields are
     // strings — that's the v1 shape `readLastSync` migrates from.
     const v1Path = globalLastSyncPath();
@@ -421,14 +421,18 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
     //    in readLastSync and the v2 write at the end of runSync ──
     await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
 
-    // The on-disk file must now be v2 and carry the per-skill SHA
-    // map. The pre-existing v1 etag/syncedAt are NOT preserved
+    // The on-disk file must now carry the CURRENT schema and the per-skill
+    // SHA map. The pre-existing v1 etag/syncedAt are NOT preserved
     // because the sync actually completed and got a fresh ETag from
     // the server. Carry-forward applies to the per-skill SHA map
     // (which was empty in v1), not to the library ETag itself.
     const afterRaw = readFileSync(v1Path, "utf-8");
     const after = JSON.parse(afterRaw);
-    assert.equal(after.schemaVersion, 2, "must persist as v2");
+    assert.equal(
+      after.schemaVersion,
+      LAST_SYNC_SCHEMA_VERSION,
+      "must persist as the current schema (v1 migrates forward on write)",
+    );
     assert.equal(after.etag, '"v2-etag"', "etag must reflect server's response");
     assert.ok(
       after.skills && typeof after.skills === "object",
@@ -502,11 +506,11 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
       "v1 migration must drop If-None-Match (placementsAreComplete returns false for empty map)",
     );
 
-    // After the recovery sync, the on-disk file is v2 with the
-    // skills map populated. The skill is on disk in the claudeProject
-    // placement — the user-visible recovery.
+    // After the recovery sync, the on-disk file carries the current
+    // schema with the skills map populated. The skill is on disk in the
+    // claudeProject placement — the user-visible recovery.
     const after = readLastSync();
-    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
     assert.ok(after.skills["alice/unmigrated"]);
     assert.ok(existsSync(resolvePlacementDir("claudeProject", "unmigrated")));
 
@@ -1014,7 +1018,7 @@ describe("additional coverage from production-readiness audit", () => {
       "runUpdate must survive a corrupt .last-sync and complete the sync",
     );
     const after = readLastSync();
-    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
     assert.equal(after.etag, '"fresh"');
     assert.ok(after.skills["alice/recovered"]);
   });

package/src/test/lib/sync.test.mjs

@@ -44,6 +44,7 @@ import {
   cliVersionBelowFloor,
   FULL_RESYNC_FLOOR,
   LAST_SYNC_SCHEMA_VERSION,
+  MIN_SYNC_INTERVAL_MS,
 } from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
@@ -124,11 +125,11 @@ describe("readLastSync / writeLastSync", () => {
     assert.equal(result.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
   });
 
-  it("writes v2 schema (LAST_SYNC_SCHEMA_VERSION === 2)", () => {
-    // Locks the constant so a future bump back to 1, or accidental
-    // change, fails loudly. The whole epic depends on v2 being the
-    // current schema and v1 files producing null (full-sync trigger).
-    assert.equal(LAST_SYNC_SCHEMA_VERSION, 2);
+  it("writes v3 schema (LAST_SYNC_SCHEMA_VERSION === 3)", () => {
+    // Locks the constant so an accidental change fails loudly. #2174
+    // bumped it 2 → 3 (adds `lastAttemptAt`). v1 files migrate in-memory,
+    // v2 files are accepted in place, unknown future versions read null.
+    assert.equal(LAST_SYNC_SCHEMA_VERSION, 3);
   });
 
   it("persists an empty skills map by default", () => {
@@ -164,7 +165,7 @@ describe("readLastSync / writeLastSync", () => {
     assert.deepEqual(result.skills, skills);
   });
 
-  it("an old v1 file migrates in-memory to a v2 shape with empty skills", () => {
+  it("an old v1 file migrates in-memory to the current-schema shape with empty skills", () => {
     // Backward compat: a user upgrading from a v1-era CLI to v2 still
     // has a v1 `.last-sync` on disk. Returning null would force a
     // full sync on every command (the etag is lost), which is
@@ -235,9 +236,9 @@ describe("readLastSync / writeLastSync", () => {
   });
 
   it("a file with an unknown schemaVersion still reads as null", () => {
-    // Forward compat: a v3 or v999 file (from a newer CLI we don't
-    // understand) reads as null, triggering a full sync. We only
-    // migrate KNOWN older shapes, not arbitrary unknown ones.
+    // Forward compat: a v4 or v999 file (from a newer CLI we don't
+    // understand) reads as null, triggering a full sync. We only accept
+    // KNOWN shapes (v1 migrate, v2/v3 in place), not arbitrary unknown ones.
     mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
     writeFileSync(
       globalLastSyncPath(),
@@ -2046,3 +2047,490 @@ describe("placementsAreComplete — direct unit coverage", () => {
     assert.equal(placementsAreComplete(skills, ["claudeCode"], false), true);
   });
 });
+
+// ── .last-sync — lastAttemptAt (v3, #2174) ─────────────────────────────
+
+describe("readLastSync / writeLastSync — lastAttemptAt (v3, #2174)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("round-trips a lastAttemptAt ISO string", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      lastAttemptAt: "2025-01-01T00:00:00.000Z",
+    });
+    assert.equal(readLastSync().lastAttemptAt, "2025-01-01T00:00:00.000Z");
+  });
+
+  it("persists lastAttemptAt: null when omitted, and reads it back as ABSENT", () => {
+    // Omitting the field writes explicit null on disk; readLastSync
+    // normalizes a non-string to absent so the throttle sees "never
+    // attempted" rather than a bogus clock value.
+    writeLastSync({ etag: '"e"', syncedAt: "s" });
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.equal(onDisk.lastAttemptAt, null);
+    assert.equal("lastAttemptAt" in readLastSync(), false);
+  });
+
+  it("coerces a non-string lastAttemptAt to absent (bogus clock ignored)", () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({
+        schemaVersion: 3,
+        etag: "x",
+        syncedAt: "x",
+        skills: {},
+        lastAttemptAt: 12345,
+      }),
+    );
+    assert.equal("lastAttemptAt" in readLastSync(), false);
+  });
+
+  it("accepts a v2 file in place (no lastAttemptAt) — etag + skills preserved", () => {
+    // A v2 file written by a pre-#2174 CLI must be read in place: etag and
+    // skills preserved (so the first post-upgrade sync stays a cheap 304),
+    // lastAttemptAt absent (the throttle treats it as "never attempted").
+    // This is the additive-forward-compat contract, distinct from the
+    // v1→v2 migration which forces a re-fetch via an empty skills map.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    const v2 = {
+      schemaVersion: 2,
+      etag: '"v2etag"',
+      syncedAt: "2025-01-01T00:00:00Z",
+      cliVersion: "4.8.1",
+      skills: {
+        "alice/x": {
+          version: "1.0.0",
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+          syncedAt: "2025-01-01T00:00:00Z",
+        },
+      },
+    };
+    writeFileSync(globalLastSyncPath(), JSON.stringify(v2));
+    const read = readLastSync();
+    assert.ok(read, "a v2 file must be accepted, not null");
+    assert.equal(read.etag, '"v2etag"');
+    assert.deepEqual(Object.keys(read.skills), ["alice/x"]);
+    assert.equal(
+      "lastAttemptAt" in read,
+      false,
+      "v2 has no lastAttemptAt → the throttle treats it as never attempted",
+    );
+  });
+
+  it("upsertLastSyncEntry preserves the prior lastAttemptAt (single-skill add is not a full sync)", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      skills: {},
+      lastAttemptAt: "2025-02-02T00:00:00.000Z",
+    });
+    upsertLastSyncEntry({
+      owner: "alice",
+      name: "added",
+      version: "1.0.0",
+      files: [
+        {
+          path: "SKILL.md",
+          content: "---\nname: added\ndescription: d\n---\nbody\n",
+        },
+      ],
+    });
+    assert.equal(
+      readLastSync().lastAttemptAt,
+      "2025-02-02T00:00:00.000Z",
+      "a single-skill add must NOT advance the throttle clock",
+    );
+  });
+
+  it("deleteLastSyncEntry preserves the prior lastAttemptAt", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      skills: {
+        "alice/gone": {
+          version: "1.0.0",
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+          syncedAt: "s",
+        },
+      },
+      lastAttemptAt: "2025-03-03T00:00:00.000Z",
+    });
+    deleteLastSyncEntry("alice", "gone");
+    assert.equal(readLastSync().lastAttemptAt, "2025-03-03T00:00:00.000Z");
+  });
+});
+
+// ── runSync — SessionStart staleness throttle (#2174) ──────────────────
+//
+// A hook-triggered sync (`throttle: true`, passed ONLY by update.mjs's
+// --session-hook / --silent branches) skips ALL network work — no library
+// GET, no receipt POST — when the last ATTEMPT was within the window. A
+// bare interactive sync (no `throttle`) always runs. `lastAttemptAt` is
+// stamped on the 304 path and every successful write, NOT on a throttled
+// skip, so the window is measured from the last REAL sync — a run of quick
+// restarts can't push the clock forward and starve the sync.
+
+describe("runSync — SessionStart throttle (#2174)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("locks the default window at 15 minutes (a change must be deliberate)", () => {
+    assert.equal(MIN_SYNC_INTERVAL_MS, 15 * 60 * 1000);
+  });
+
+  it("ACCEPTANCE: two throttled syncs within the window → the 2nd makes ZERO HTTP calls", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // Run 1 (hook-triggered): a real sync — no prior attempt, so it is NOT
+    // throttled. It stamps lastAttemptAt = now.
+    const first = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(first.throttled ?? false, false, "first run is a real sync");
+    assert.ok(server.getLibraryRequestCount() >= 1, "first run hit the library GET");
+
+    // Reset the request-count spies, then run again immediately. Within the
+    // 15-min window the throttle MUST skip both the library GET and the
+    // receipt POST — zero HTTP, the acceptance criterion.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    const second = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+
+    assert.equal(second.throttled, true, "second run within the window is throttled");
+    assert.equal(server.getLibraryRequestCount(), 0, "throttled run makes NO library GET");
+    assert.equal(server.getReceiptRequestCount(), 0, "throttled run makes NO receipt POST");
+    assert.equal(
+      second.notModified,
+      false,
+      "throttled is distinct from a 304 — we never contacted the server",
+    );
+  });
+
+  it("a bare interactive sync (no throttle) ALWAYS syncs, even within the window", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Arm the clock with a hook sync.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    // Interactive: `throttle` omitted → must hit the network despite a
+    // fresh lastAttemptAt.
+    const res = await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "an explicit interactive sync always contacts the server",
+    );
+  });
+
+  it("does NOT throttle a fresh install (no lastAttemptAt yet)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // No prior .last-sync → lastAttemptAt absent → never attempted → the
+    // very first hook sync proceeds.
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("throttle expires: an attempt older than the window syncs again", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // Backdate lastAttemptAt to just past the window.
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - MIN_SYNC_INTERVAL_MS - 1000).toISOString(),
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "past the window → not throttled");
+    assert.ok(server.getLibraryRequestCount() >= 1, "expired window re-contacts the server");
+  });
+
+  it("minSyncIntervalMs override pins the boundary (0 disables the throttle)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+    // interval 0 → `now - last < 0` is never true → always syncs.
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 0,
+    });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("brackets the window: a 1h-old attempt throttles under a 2h interval, syncs under a 30-min one", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+    });
+
+    // Inside a 2h window → throttled (zero HTTP). A throttled skip does
+    // not re-stamp, so the same 1h-old attempt then drives the second leg.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    const inside = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 2 * 60 * 60 * 1000,
+    });
+    assert.equal(inside.throttled, true, "1h elapsed < 2h window → throttled");
+    assert.equal(server.getLibraryRequestCount(), 0);
+
+    // Outside a 30-min window → syncs.
+    const outside = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 30 * 60 * 1000,
+    });
+    assert.equal(outside.throttled ?? false, false, "1h elapsed >= 30-min window → syncs");
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("a FUTURE lastAttemptAt (backward clock jump) syncs and self-heals instead of throttling until the clock catches up", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // A backward clock jump (NTP correction, VM snapshot restore) leaves a
+    // stamp that is now in the FUTURE. `now - lastAttemptMs` goes negative —
+    // an unguarded `< intervalMs` would throttle every hook sync until the
+    // wall clock catches up, silently (hook modes are contract-silent).
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "a future stamp must NOT throttle");
+    assert.ok(server.getLibraryRequestCount() >= 1, "the hook sync proceeded");
+    // The sync (304 path here) re-stamps a sane "now" — the bogus future
+    // value is gone after ONE pass; the next window measures from reality.
+    const healed = readLastSync().lastAttemptAt;
+    assert.ok(
+      new Date(healed).getTime() <= Date.now(),
+      "the sync self-healed the stamp back to a non-future time",
+    );
+  });
+
+  it("a malformed lastAttemptAt string ('not-a-date') is not trusted — the hook sync proceeds", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // readLastSync only normalizes NON-string values to absent; a string
+    // that fails Date.parse reaches runSync's Number.isFinite guard. This
+    // pins that guard: bogus clock → sync (safe direction), never throttle.
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: "not-a-date",
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "unparseable stamp must NOT throttle");
+    assert.ok(server.getLibraryRequestCount() >= 1, "the hook sync proceeded");
+    const healed = readLastSync().lastAttemptAt;
+    assert.ok(
+      typeof healed === "string" && Number.isFinite(Date.parse(healed)),
+      "the sync replaced the malformed stamp with a valid timestamp",
+    );
+  });
+
+  it("304 path stamps lastAttemptAt — LOAD-BEARING so the throttle re-arms every steady-state session", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // First (interactive) sync stamps lastAttemptAt and the etag.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(
+      typeof readLastSync().lastAttemptAt,
+      "string",
+      "first sync stamped lastAttemptAt",
+    );
+
+    // Backdate so the next sync is NOT throttled but WILL 304 (etag matches,
+    // placement present).
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+    });
+
+    // Snapshot the full pre-304 state — the re-stamp must move ONLY the
+    // attempt clock. etag/skills/cliVersion wiped here (e.g. a future
+    // edit letting `skills` default to {}) would silently destroy every
+    // user's per-skill SHA cache on their next up-to-date sync.
+    const before = readLastSync();
+
+    const res = await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(res.notModified, true, "etag match → 304");
+    const after = readLastSync();
+    assert.equal(typeof after.lastAttemptAt, "string");
+    assert.ok(
+      Date.now() - new Date(after.lastAttemptAt).getTime() < 60_000,
+      "the 304 path re-stamped lastAttemptAt to a fresh time (throttle re-arms)",
+    );
+    assert.equal(after.etag, before.etag, "304 re-stamp preserves the etag verbatim");
+    assert.deepEqual(
+      after.skills,
+      before.skills,
+      "304 re-stamp preserves the per-skill SHA map verbatim",
+    );
+    assert.equal(
+      after.cliVersion,
+      before.cliVersion,
+      "304 re-stamp preserves cliVersion (a 304 is not a membership heal)",
+    );
+    assert.equal(after.syncedAt, before.syncedAt, "304 re-stamp preserves syncedAt");
+  });
+
+  it("does NOT stamp lastAttemptAt on a filesIncomplete sync (a broken sync is retried, not throttled)", async () => {
+    const inc = makeSkill("inc");
+    inc.filesIncomplete = true;
+    server.setEtag('"v1"');
+    server.setLibraryResponse({ skills: [inc], removals: [], syncedAt: "x" });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    // filesIncomplete → the whole state-file write is skipped → no
+    // lastAttemptAt persisted → the next hook sync is NOT throttled.
+    assert.equal(readLastSync(), null, "no state persisted on filesIncomplete");
+  });
+
+  it("emits a SKILLREPO_VERBOSE stderr line when it throttles", async () => {
+    const { createCaptureStream } = await import("../helpers/capture-stream.mjs");
+    const stderr = createCaptureStream();
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+
+    const prevVerbose = process.env.SKILLREPO_VERBOSE;
+    process.env.SKILLREPO_VERBOSE = "1";
+    try {
+      const res = await runSync({
+        serverUrl,
+        apiKey: VALID_KEY,
+        vendors: ["claudeCode"],
+        throttle: true,
+        io: { stderr },
+      });
+      assert.equal(res.throttled, true);
+    } finally {
+      if (prevVerbose === undefined) delete process.env.SKILLREPO_VERBOSE;
+      else process.env.SKILLREPO_VERBOSE = prevVerbose;
+    }
+    assert.match(stderr.text(), /throttled/);
+    assert.equal(server.getLibraryRequestCount(), 0, "verbose throttle still makes no GET");
+  });
+});