@moxxy/plugin-usage-stats 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -1,13 +1,26 @@
-import { type Plugin } from '@moxxy/sdk';
+import { type Plugin, type SkillCreatedEvent, type SkillInvokedEvent } from '@moxxy/sdk';
+import { type SkillUsageDelta } from '@moxxy/core';
 export interface BuildUsageStatsPluginOptions {
-    /** Override the on-disk aggregate path. Tests inject a tmp file here. */
+    /** Override the on-disk token-usage aggregate path. Tests inject a tmp file here. */
     readonly statsPath?: string;
+    /** Override the on-disk skill-usage aggregate path. Tests inject a tmp file here. */
+    readonly skillUsagePath?: string;
 }
 /**
- * Records cross-session token usage. On shutdown it folds THIS run's
+ * Records cross-session token AND skill usage. On shutdown it folds THIS run's
  * `provider_response` events by `<provider>/<model>` and merges the delta into
  * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
- * and `/usage clear` resets.
+ * and `/usage clear` resets. It ALSO folds this run's `skill_invoked` /
+ * `skill_created` events by skill name and merges them into
+ * `~/.moxxy/skills/.meta/usage.json` (surfaced in `/skills` and
+ * `moxxy skills list`). Both folds use the same resume/`/new` seq boundary, so
+ * each store counts a session's contribution exactly once.
+ *
+ * NOTE: `skill_invoked` is only emitted by the `load_skill` tool today (reason
+ * `'load_skill_tool'`), so the skill store counts explicit `load_skill` calls
+ * only — see `@moxxy/core`'s `skill-usage.ts`. The other reasons the event type
+ * allows (`trigger_match` / `classifier` / `manual`) have no emission site yet;
+ * when they land, this same fold starts counting them with no change here.
  *
  * Resume-safe by construction: restored events are seeded into the log WITHOUT
  * firing subscribers, and `onInit` runs after seeding. `onInit` records the
@@ -33,5 +46,14 @@ export interface BuildUsageStatsPluginOptions {
  * when the hooks are invoked directly (outside the host's lifecycle dispatcher).
  */
 export declare function buildUsageStatsPlugin(opts?: BuildUsageStatsPluginOptions): Plugin;
+/**
+ * Fold a run's live `skill_invoked` / `skill_created` events into a per-skill-
+ * name delta for `mergeSkillUsage`. Invocations are counted and the latest
+ * invocation timestamp kept; a creation event records the skill's `createdAt`.
+ * Timestamps convert the epoch-ms event `ts` to ISO to match the store's shape.
+ * Skills that only appear in a creation event still get an entry (invocations 0)
+ * so a freshly-synthesized-but-never-invoked skill still records its birth.
+ */
+export declare function summarizeSkillEvents(invoked: ReadonlyArray<SkillInvokedEvent>, created: ReadonlyArray<SkillCreatedEvent>): Record<string, SkillUsageDelta>;
 export default buildUsageStatsPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,4BAAiC,GAAG,MAAM,CA4FrF;AAmBD,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,MAAM,EAEX,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAErF,MAAM,WAAW,4BAA4B;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,4BAAiC,GAAG,MAAM,CAmHrF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACzC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CA+BjC;AA6BD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,10 +1,20 @@
 import { definePlugin, summarizeTokensByModel, } from '@moxxy/sdk';
-import { mergeUsageStats } from '@moxxy/core';
+import { mergeSkillUsage, mergeUsageStats } from '@moxxy/core';
 /**
- * Records cross-session token usage. On shutdown it folds THIS run's
+ * Records cross-session token AND skill usage. On shutdown it folds THIS run's
  * `provider_response` events by `<provider>/<model>` and merges the delta into
  * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
- * and `/usage clear` resets.
+ * and `/usage clear` resets. It ALSO folds this run's `skill_invoked` /
+ * `skill_created` events by skill name and merges them into
+ * `~/.moxxy/skills/.meta/usage.json` (surfaced in `/skills` and
+ * `moxxy skills list`). Both folds use the same resume/`/new` seq boundary, so
+ * each store counts a session's contribution exactly once.
+ *
+ * NOTE: `skill_invoked` is only emitted by the `load_skill` tool today (reason
+ * `'load_skill_tool'`), so the skill store counts explicit `load_skill` calls
+ * only — see `@moxxy/core`'s `skill-usage.ts`. The other reasons the event type
+ * allows (`trigger_match` / `classifier` / `manual`) have no emission site yet;
+ * when they land, this same fold starts counting them with no change here.
  *
  * Resume-safe by construction: restored events are seeded into the log WITHOUT
  * firing subscribers, and `onInit` runs after seeding. `onInit` records the
@@ -105,35 +115,102 @@ export function buildUsageStatsPlugin(opts = {}) {
                 cursors.delete(ctx.sessionId);
                 // Best-effort: a throwing reader or a failed fold degrades to "record
                 // nothing for this run" rather than rejecting the hook (which the host
-                // would log as a spurious failure). `mergeUsageStats` already swallows
-                // its own write errors; this guards the read/fold side too.
+                // would log as a spurious failure). Each store folds in its own guarded
+                // block so a failure folding one family (tokens / skills) can't strand
+                // the other, and neither can crash the 5s-timeboxed shutdown path.
+                // `mergeUsageStats` / `mergeSkillUsage` already swallow their own write
+                // errors; these guards cover the read/fold side too.
+                // Only `provider_response` events carry token usage; scan that indexed
+                // subset (O(matches)) instead of copying + filtering the full event log
+                // (O(total session events)).
                 try {
-                    // Only `provider_response` events carry token usage; scan that indexed
-                    // subset (O(matches)) instead of copying + filtering the full event log
-                    // (O(total session events)) on this 5s-timeboxed shutdown path.
                     const responses = ctx.log.ofType('provider_response');
                     const live = initMaxSeq === null ? responses : responses.filter((e) => e.seq > initMaxSeq);
-                    if (live.length === 0)
-                        return;
-                    const delta = summarizeTokensByModel(live);
-                    await mergeUsageStats(delta, opts.statsPath);
+                    if (live.length > 0) {
+                        const delta = summarizeTokensByModel(live);
+                        await mergeUsageStats(delta, opts.statsPath);
+                    }
+                }
+                catch {
+                    // Drop this run's token usage rather than crash shutdown — explicitly
+                    // the accepted trade-off for an optional, contention-free aggregate.
+                }
+                // Fold this run's live skill events past the SAME boundary and merge the
+                // per-skill-name delta into `~/.moxxy/skills/.meta/usage.json`.
+                try {
+                    const invoked = ctx.log.ofType('skill_invoked');
+                    const created = ctx.log.ofType('skill_created');
+                    const skillDelta = summarizeSkillEvents(initMaxSeq === null ? invoked : invoked.filter((e) => e.seq > initMaxSeq), initMaxSeq === null ? created : created.filter((e) => e.seq > initMaxSeq));
+                    // Only touch disk (even the read side) when there's something to add.
+                    if (Object.keys(skillDelta).length > 0) {
+                        await mergeSkillUsage(skillDelta, opts.skillUsagePath);
+                    }
                 }
                 catch {
-                    // Drop this run's usage rather than crash shutdown — explicitly the
-                    // accepted trade-off for an optional, contention-free aggregate.
+                    // Drop this run's skill usage rather than crash shutdown — same
+                    // best-effort trade-off as the token fold above.
                 }
             },
         },
     });
 }
+/**
+ * Fold a run's live `skill_invoked` / `skill_created` events into a per-skill-
+ * name delta for `mergeSkillUsage`. Invocations are counted and the latest
+ * invocation timestamp kept; a creation event records the skill's `createdAt`.
+ * Timestamps convert the epoch-ms event `ts` to ISO to match the store's shape.
+ * Skills that only appear in a creation event still get an entry (invocations 0)
+ * so a freshly-synthesized-but-never-invoked skill still records its birth.
+ */
+export function summarizeSkillEvents(invoked, created) {
+    const acc = new Map();
+    const entry = (name) => {
+        let e = acc.get(name);
+        if (!e) {
+            e = { invocations: 0 };
+            acc.set(name, e);
+        }
+        return e;
+    };
+    for (const e of invoked) {
+        const cur = entry(e.name);
+        cur.invocations += 1;
+        const iso = new Date(e.ts).toISOString();
+        if (!cur.lastInvokedAt || iso > cur.lastInvokedAt)
+            cur.lastInvokedAt = iso;
+    }
+    for (const e of created) {
+        const cur = entry(e.name);
+        const iso = new Date(e.ts).toISOString();
+        // Earliest creation wins if (improbably) a name is created twice in one run.
+        if (!cur.createdAt || iso < cur.createdAt)
+            cur.createdAt = iso;
+    }
+    const out = {};
+    for (const [name, e] of acc) {
+        out[name] = {
+            invocations: e.invocations,
+            ...(e.lastInvokedAt ? { lastInvokedAt: e.lastInvokedAt } : {}),
+            ...(e.createdAt ? { createdAt: e.createdAt } : {}),
+        };
+    }
+    return out;
+}
+// The event families `onShutdown` folds. The `baseSeq`-less fallback in
+// `boundarySeq` must scan the union of these so the resume boundary excludes
+// every restored event of ANY folded family — otherwise a session whose
+// restored prefix has, e.g., skill events but no `provider_response` would get a
+// too-low boundary and re-fold (double-count) those restored skill events.
+const FOLDED_EVENT_TYPES = ['provider_response', 'skill_invoked', 'skill_created'];
 /**
  * Highest held seq — the resume boundary — without copying the log. Prefers the
  * O(1) `baseSeq + length - 1` identity (every held event has `seq === base +
- * index`); falls back to scanning the indexed `provider_response` subset when a
- * reader doesn't expose `baseSeq`. `null` for an empty log. Using the response
- * subset for the fallback is sound: `onShutdown` only folds responses, so a
- * boundary at the max restored response seq still excludes every restored
- * response and includes every live one.
+ * index`); falls back to scanning the indexed subsets `onShutdown` folds when a
+ * reader doesn't expose `baseSeq`. `null` for an empty log. Scanning the union
+ * of folded families (not just `provider_response`) keeps the fallback sound now
+ * that skills are folded too: the boundary sits at the max restored seq across
+ * every folded family, so each fold excludes its restored events and includes
+ * only its live ones.
  */
 function boundarySeq(log) {
     if (log.length === 0)
@@ -141,9 +218,11 @@ function boundarySeq(log) {
     if (typeof log.baseSeq === 'number')
         return log.baseSeq + log.length - 1;
     let max = null;
-    for (const e of log.ofType('provider_response'))
-        if (max === null || e.seq > max)
-            max = e.seq;
+    for (const type of FOLDED_EVENT_TYPES) {
+        for (const e of log.ofType(type))
+            if (max === null || e.seq > max)
+                max = e.seq;
+    }
     return max;
 }
 export default buildUsageStatsPlugin;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/plugin-usage-stats",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Records cross-session token usage. On session close it folds this run's provider_response events by provider/model and merges the delta into ~/.moxxy/usage.json (a forward-going aggregate surfaced in the /usage panel and reset by /usage clear).",
   "keywords": [
     "moxxy",
@@ -43,15 +43,15 @@
     }
   },
   "dependencies": {
-    "@moxxy/core": "0.26.0",
-    "@moxxy/sdk": "0.26.0"
+    "@moxxy/core": "0.28.0",
+    "@moxxy/sdk": "0.28.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8",
-    "@moxxy/tsconfig": "0.0.0",
-    "@moxxy/vitest-preset": "0.0.0"
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/index.test.ts

@@ -5,13 +5,14 @@ import * as path from 'node:path';
 import {
   asEventId,
   asSessionId,
+  asSkillId,
   asTurnId,
   type AppContext,
   type EventLogReader,
   type MoxxyEvent,
 } from '@moxxy/sdk';
-import { loadUsageStats } from '@moxxy/core';
-import { buildUsageStatsPlugin } from './index.js';
+import { loadSkillUsage, loadUsageStats } from '@moxxy/core';
+import { buildUsageStatsPlugin, summarizeSkillEvents } from './index.js';
 
 const sid = asSessionId('s1');
 const tid = asTurnId('t1');
@@ -32,6 +33,38 @@ function resp(seq: number, model: string, inputTokens: number): MoxxyEvent {
   } as MoxxyEvent;
 }
 
+function skillInvoked(seq: number, name: string, ts: number): MoxxyEvent {
+  return {
+    id: asEventId(`e${seq}`),
+    seq,
+    ts,
+    sessionId: sid,
+    turnId: tid,
+    source: 'model',
+    type: 'skill_invoked',
+    skillId: asSkillId(name),
+    name,
+    reason: 'load_skill_tool',
+  } as MoxxyEvent;
+}
+
+function skillCreated(seq: number, name: string, ts: number): MoxxyEvent {
+  return {
+    id: asEventId(`e${seq}`),
+    seq,
+    ts,
+    sessionId: sid,
+    turnId: tid,
+    source: 'model',
+    type: 'skill_created',
+    skillId: asSkillId(name),
+    name,
+    path: `/tmp/${name}.md`,
+    scope: 'user',
+    originatingPrompt: `make ${name}`,
+  } as MoxxyEvent;
+}
+
 function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
   // Faithfully model the real EventLog: `length` is a COUNT of held events,
   // while `slice(from)`/`at(seq)` are SEQ-addressed (translated through the
@@ -115,10 +148,12 @@ function ctxForLog(log: FakeLog, sessionId = sid): AppContext {
 
 let tmpDir: string;
 let statsPath: string;
+let skillUsagePath: string;
 
 beforeEach(async () => {
   tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-usage-plugin-'));
   statsPath = path.join(tmpDir, 'usage.json');
+  skillUsagePath = path.join(tmpDir, 'skill-usage.json');
 });
 
 afterEach(async () => {
@@ -455,3 +490,80 @@ describe('usage-stats plugin', () => {
     expect(file.models['anthropic/opus']!.inputTokens).toBe(50);
   });
 });
+
+describe('summarizeSkillEvents', () => {
+  it('counts invocations per name and keeps the latest invocation timestamp', () => {
+    const delta = summarizeSkillEvents(
+      [skillInvoked(0, 'deploy', 1000), skillInvoked(1, 'deploy', 3000), skillInvoked(2, 'lint', 2000)],
+      [],
+    );
+    expect(delta['deploy']!.invocations).toBe(2);
+    expect(delta['deploy']!.lastInvokedAt).toBe(new Date(3000).toISOString());
+    expect(delta['lint']!.invocations).toBe(1);
+  });
+
+  it('records createdAt for a created-but-never-invoked skill (invocations 0)', () => {
+    const delta = summarizeSkillEvents([], [skillCreated(0, 'fresh', 5000)]);
+    expect(delta['fresh']!.invocations).toBe(0);
+    expect(delta['fresh']!.createdAt).toBe(new Date(5000).toISOString());
+  });
+
+  it('is empty for no events', () => {
+    expect(summarizeSkillEvents([], [])).toEqual({});
+  });
+});
+
+describe('usage-stats plugin — skill folding', () => {
+  it('folds skill_invoked/skill_created into the skill usage store on shutdown', async () => {
+    const plugin = buildUsageStatsPlugin({ statsPath, skillUsagePath });
+    const events = [
+      skillCreated(0, 'deploy', 1000),
+      skillInvoked(1, 'deploy', 2000),
+      skillInvoked(2, 'deploy', 4000),
+      skillInvoked(3, 'lint', 3000),
+    ];
+
+    await plugin.hooks!.onInit!(ctxFor([]));
+    await plugin.hooks!.onShutdown!(ctxFor(events));
+
+    const file = await loadSkillUsage(skillUsagePath);
+    expect(file.skills['deploy']!.invocations).toBe(2);
+    expect(file.skills['deploy']!.createdAt).toBe(new Date(1000).toISOString());
+    expect(file.skills['deploy']!.lastInvokedAt).toBe(new Date(4000).toISOString());
+    expect(file.skills['lint']!.invocations).toBe(1);
+  });
+
+  it('counts only the live skill suffix on resume (skips restored skill events)', async () => {
+    const restored = [skillInvoked(0, 'deploy', 1000), skillInvoked(1, 'deploy', 2000)];
+    const live = [skillInvoked(2, 'deploy', 3000)];
+    const plugin = buildUsageStatsPlugin({ statsPath, skillUsagePath });
+
+    await plugin.hooks!.onInit!(ctxFor(restored));
+    await plugin.hooks!.onShutdown!(ctxFor([...restored, ...live]));
+
+    // Only the single live invocation is counted — not the 2 restored.
+    expect((await loadSkillUsage(skillUsagePath)).skills['deploy']!.invocations).toBe(1);
+  });
+
+  it('folds skill usage even when the run produced no provider_response (no token early-return)', async () => {
+    // Regression: the token fold used to `return` early when no responses were
+    // present, which would skip the skill fold entirely. They must be independent.
+    const plugin = buildUsageStatsPlugin({ statsPath, skillUsagePath });
+    const events = [skillInvoked(0, 'deploy', 1000)];
+
+    await plugin.hooks!.onInit!(ctxFor([]));
+    await plugin.hooks!.onShutdown!(ctxFor(events));
+
+    expect((await loadSkillUsage(skillUsagePath)).skills['deploy']!.invocations).toBe(1);
+    // No token usage was recorded (no provider_response events).
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('writes no skill usage file when the run exercised no skills', async () => {
+    const plugin = buildUsageStatsPlugin({ statsPath, skillUsagePath });
+    await plugin.hooks!.onInit!(ctxFor([]));
+    await plugin.hooks!.onShutdown!(ctxFor([resp(0, 'opus', 100)]));
+    // Empty skill delta → merge never touches disk.
+    await expect(fs.access(skillUsagePath)).rejects.toThrow();
+  });
+});

package/src/index.ts

@@ -4,12 +4,16 @@ import {
   type EventLogReader,
   type Plugin,
   type SessionId,
+  type SkillCreatedEvent,
+  type SkillInvokedEvent,
 } from '@moxxy/sdk';
-import { mergeUsageStats } from '@moxxy/core';
+import { mergeSkillUsage, mergeUsageStats, type SkillUsageDelta } from '@moxxy/core';
 
 export interface BuildUsageStatsPluginOptions {
-  /** Override the on-disk aggregate path. Tests inject a tmp file here. */
+  /** Override the on-disk token-usage aggregate path. Tests inject a tmp file here. */
   readonly statsPath?: string;
+  /** Override the on-disk skill-usage aggregate path. Tests inject a tmp file here. */
+  readonly skillUsagePath?: string;
 }
 
 /**
@@ -27,10 +31,20 @@ interface EventLogExtras {
 }
 
 /**
- * Records cross-session token usage. On shutdown it folds THIS run's
+ * Records cross-session token AND skill usage. On shutdown it folds THIS run's
  * `provider_response` events by `<provider>/<model>` and merges the delta into
  * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
- * and `/usage clear` resets.
+ * and `/usage clear` resets. It ALSO folds this run's `skill_invoked` /
+ * `skill_created` events by skill name and merges them into
+ * `~/.moxxy/skills/.meta/usage.json` (surfaced in `/skills` and
+ * `moxxy skills list`). Both folds use the same resume/`/new` seq boundary, so
+ * each store counts a session's contribution exactly once.
+ *
+ * NOTE: `skill_invoked` is only emitted by the `load_skill` tool today (reason
+ * `'load_skill_tool'`), so the skill store counts explicit `load_skill` calls
+ * only — see `@moxxy/core`'s `skill-usage.ts`. The other reasons the event type
+ * allows (`trigger_match` / `classifier` / `manual`) have no emission site yet;
+ * when they land, this same fold starts counting them with no change here.
  *
  * Resume-safe by construction: restored events are seeded into the log WITHOUT
  * firing subscribers, and `onInit` runs after seeding. `onInit` records the
@@ -128,41 +142,118 @@ export function buildUsageStatsPlugin(opts: BuildUsageStatsPluginOptions = {}):
         cursors.delete(ctx.sessionId);
         // Best-effort: a throwing reader or a failed fold degrades to "record
         // nothing for this run" rather than rejecting the hook (which the host
-        // would log as a spurious failure). `mergeUsageStats` already swallows
-        // its own write errors; this guards the read/fold side too.
+        // would log as a spurious failure). Each store folds in its own guarded
+        // block so a failure folding one family (tokens / skills) can't strand
+        // the other, and neither can crash the 5s-timeboxed shutdown path.
+        // `mergeUsageStats` / `mergeSkillUsage` already swallow their own write
+        // errors; these guards cover the read/fold side too.
+
+        // Only `provider_response` events carry token usage; scan that indexed
+        // subset (O(matches)) instead of copying + filtering the full event log
+        // (O(total session events)).
         try {
-          // Only `provider_response` events carry token usage; scan that indexed
-          // subset (O(matches)) instead of copying + filtering the full event log
-          // (O(total session events)) on this 5s-timeboxed shutdown path.
           const responses = ctx.log.ofType('provider_response');
           const live =
             initMaxSeq === null ? responses : responses.filter((e) => e.seq > initMaxSeq);
-          if (live.length === 0) return;
-          const delta = summarizeTokensByModel(live);
-          await mergeUsageStats(delta, opts.statsPath);
+          if (live.length > 0) {
+            const delta = summarizeTokensByModel(live);
+            await mergeUsageStats(delta, opts.statsPath);
+          }
         } catch {
-          // Drop this run's usage rather than crash shutdown — explicitly the
-          // accepted trade-off for an optional, contention-free aggregate.
+          // Drop this run's token usage rather than crash shutdown — explicitly
+          // the accepted trade-off for an optional, contention-free aggregate.
+        }
+
+        // Fold this run's live skill events past the SAME boundary and merge the
+        // per-skill-name delta into `~/.moxxy/skills/.meta/usage.json`.
+        try {
+          const invoked = ctx.log.ofType('skill_invoked');
+          const created = ctx.log.ofType('skill_created');
+          const skillDelta = summarizeSkillEvents(
+            initMaxSeq === null ? invoked : invoked.filter((e) => e.seq > initMaxSeq),
+            initMaxSeq === null ? created : created.filter((e) => e.seq > initMaxSeq),
+          );
+          // Only touch disk (even the read side) when there's something to add.
+          if (Object.keys(skillDelta).length > 0) {
+            await mergeSkillUsage(skillDelta, opts.skillUsagePath);
+          }
+        } catch {
+          // Drop this run's skill usage rather than crash shutdown — same
+          // best-effort trade-off as the token fold above.
         }
       },
     },
   });
 }
 
+/**
+ * Fold a run's live `skill_invoked` / `skill_created` events into a per-skill-
+ * name delta for `mergeSkillUsage`. Invocations are counted and the latest
+ * invocation timestamp kept; a creation event records the skill's `createdAt`.
+ * Timestamps convert the epoch-ms event `ts` to ISO to match the store's shape.
+ * Skills that only appear in a creation event still get an entry (invocations 0)
+ * so a freshly-synthesized-but-never-invoked skill still records its birth.
+ */
+export function summarizeSkillEvents(
+  invoked: ReadonlyArray<SkillInvokedEvent>,
+  created: ReadonlyArray<SkillCreatedEvent>,
+): Record<string, SkillUsageDelta> {
+  const acc = new Map<string, { invocations: number; lastInvokedAt?: string; createdAt?: string }>();
+  const entry = (name: string) => {
+    let e = acc.get(name);
+    if (!e) {
+      e = { invocations: 0 };
+      acc.set(name, e);
+    }
+    return e;
+  };
+  for (const e of invoked) {
+    const cur = entry(e.name);
+    cur.invocations += 1;
+    const iso = new Date(e.ts).toISOString();
+    if (!cur.lastInvokedAt || iso > cur.lastInvokedAt) cur.lastInvokedAt = iso;
+  }
+  for (const e of created) {
+    const cur = entry(e.name);
+    const iso = new Date(e.ts).toISOString();
+    // Earliest creation wins if (improbably) a name is created twice in one run.
+    if (!cur.createdAt || iso < cur.createdAt) cur.createdAt = iso;
+  }
+  const out: Record<string, SkillUsageDelta> = {};
+  for (const [name, e] of acc) {
+    out[name] = {
+      invocations: e.invocations,
+      ...(e.lastInvokedAt ? { lastInvokedAt: e.lastInvokedAt } : {}),
+      ...(e.createdAt ? { createdAt: e.createdAt } : {}),
+    };
+  }
+  return out;
+}
+
+// The event families `onShutdown` folds. The `baseSeq`-less fallback in
+// `boundarySeq` must scan the union of these so the resume boundary excludes
+// every restored event of ANY folded family — otherwise a session whose
+// restored prefix has, e.g., skill events but no `provider_response` would get a
+// too-low boundary and re-fold (double-count) those restored skill events.
+const FOLDED_EVENT_TYPES = ['provider_response', 'skill_invoked', 'skill_created'] as const;
+
 /**
  * Highest held seq — the resume boundary — without copying the log. Prefers the
  * O(1) `baseSeq + length - 1` identity (every held event has `seq === base +
- * index`); falls back to scanning the indexed `provider_response` subset when a
- * reader doesn't expose `baseSeq`. `null` for an empty log. Using the response
- * subset for the fallback is sound: `onShutdown` only folds responses, so a
- * boundary at the max restored response seq still excludes every restored
- * response and includes every live one.
+ * index`); falls back to scanning the indexed subsets `onShutdown` folds when a
+ * reader doesn't expose `baseSeq`. `null` for an empty log. Scanning the union
+ * of folded families (not just `provider_response`) keeps the fallback sound now
+ * that skills are folded too: the boundary sits at the max restored seq across
+ * every folded family, so each fold excludes its restored events and includes
+ * only its live ones.
  */
 function boundarySeq(log: EventLogReader & EventLogExtras): number | null {
   if (log.length === 0) return null;
   if (typeof log.baseSeq === 'number') return log.baseSeq + log.length - 1;
   let max: number | null = null;
-  for (const e of log.ofType('provider_response')) if (max === null || e.seq > max) max = e.seq;
+  for (const type of FOLDED_EVENT_TYPES) {
+    for (const e of log.ofType(type)) if (max === null || e.seq > max) max = e.seq;
+  }
   return max;
 }