@senpi/runtime 3.0.162 → 3.0.168

package/dist/skills-manager/coordinator.d.ts

@@ -138,9 +138,10 @@ export declare class SkillsUpdateCoordinator {
      * Per-skill errors are recorded in state without aborting the others;
      * outcomes are logged (no notification).
      *
-     * If the clone itself fails we log and return without touching state — a
-     * full-clone failure is almost always a transient network/git issue that
-     * affects every skill equally. The next tick retries.
+     * A failed clone comes back from `withClonedGroups` as a per-skill `clone`
+     * outcome and is recorded like any other install failure. Only a throw from
+     * `cloneAndInstallMany` itself (the injected `cloneAndInstall` in tests)
+     * returns without touching state. The next tick retries either way.
      */
     private applyUpdates;
     /**
@@ -248,6 +249,34 @@ export declare class SkillsUpdateCoordinator {
      * state rather than stale pre-action data.
      */
     private buildSnapshot;
+    /**
+     * Skills whose failed install could not put the previous install back (`rolled_back=false`), so
+     * the skill dir is gone. Filled by `emitInstallFailed`, read and cleared by the next
+     * `emitCheckCompleted`. Runs are serialized on `operationChain`, so one run never sees another's.
+     */
+    private readonly skillDirsLost;
+    /**
+     * What the last check run in this process saw on disk, per skill (`null` = nothing there). A run
+     * that checks only some skills (`updateSkill`) reports the rest from here, not from persisted
+     * state, which keeps the last non-null version.
+     */
+    private readonly lastOnDisk;
+    /**
+     * Emit a catalogued `skills.*` event, guarded so a throwing sink or a bad attribute shape can
+     * never disturb a tick, a manual update or bootstrap.
+     */
+    private emitEvent;
+    /** `skills.check_completed`: one summary per check run, with the whole managed set's versions. */
+    private emitCheckCompleted;
+    /** `skills.installed` or `skills.install_failed` for one processed install outcome. */
+    private emitInstallOutcome;
+    private emitInstalled;
+    /** `skills.install_failed`. The original thrown value rides the `error` slot, stack and all. */
+    private emitInstallFailed;
+    /** `skills.bootstrap_completed` plus one `skills.installed` / `skills.install_failed` per attempt. */
+    private emitBootstrapEvents;
+    /** Source for event attrs only; a resolve failure drops the source attrs instead of throwing. */
+    private resolveSourceForTelemetry;
     private persistState;
 }
 //# sourceMappingURL=coordinator.d.ts.map

package/dist/skills-manager/coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/skills-manager/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,KAAK,EAMV,qBAAqB,EAGrB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAGpB,qBAAa,iCAAkC,SAAQ,KAAK;gBAC9C,OAAO,EAAE,MAAM;CAI5B;AAkCD,qBAAa,uBAAuB;IAatB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAyD;IACtE,OAAO,CAAC,QAAQ,CAAwB;IACxC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAoC;gBAE7B,OAAO,EAAE,8BAA8B;IAKpE;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B5B;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBlC,iEAAiE;IACjE,WAAW,IAAI,qBAAqB;IAMpC;;;;;;;;;;OAUG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAkGxD;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CACxB,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAClF;IA0ID;;;OAGG;YACW,aAAa;IAwB3B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAqBpC;;;OAGG;YACW,OAAO;IAuGrB;;;;;;;;OAQG;YACW,YAAY;IAmC1B;;;;;;;;;;;OAWG;YACW,mBAAmB;IAwFjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;;;;OAQG;YACW,WAAW;IAmDzB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;YA4CP,YAAY;CAS3B"}
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/skills-manager/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,KAAK,EAQV,qBAAqB,EAIrB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AA6CpB,qBAAa,iCAAkC,SAAQ,KAAK;gBAC9C,OAAO,EAAE,MAAM;CAI5B;AAkCD,qBAAa,uBAAuB;IAatB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAyD;IACtE,OAAO,CAAC,QAAQ,CAAwB;IACxC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAoC;gBAE7B,OAAO,EAAE,8BAA8B;IAKpE;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC5B;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BlC,iEAAiE;IACjE,WAAW,IAAI,qBAAqB;IAMpC;;;;;;;;;;OAUG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAiHxD;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CACxB,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAClF;IAyJD;;;OAGG;YACW,aAAa;IAwB3B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAqBpC;;;OAGG;YACW,OAAO;IAgHrB;;;;;;;;;OASG;YACW,YAAY;IA+C1B;;;;;;;;;;;OAWG;YACW,mBAAmB;IAmGjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IA8B7B;;;;;;;;OAQG;YACW,WAAW;IAsDzB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;IA+CrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D;;;OAGG;IACH,OAAO,CAAC,SAAS;IAQjB,kGAAkG;IAClG,OAAO,CAAC,kBAAkB;IA4E1B,uFAAuF;IACvF,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,aAAa;IAoBrB,gGAAgG;IAChG,OAAO,CAAC,iBAAiB;IA6BzB,sGAAsG;IACtG,OAAO,CAAC,mBAAmB;IAwB3B,iGAAiG;IACjG,OAAO,CAAC,yBAAyB;YAQnB,YAAY;CAS3B"}

package/dist/skills-manager/coordinator.js

@@ -29,7 +29,21 @@ import { parseSemver } from "../runtime/auto-update/policy.js";
 import { SkillsManagerStateStore } from "./state-store.js";
 import { checkSkillVersion, normalizeVersion } from "./version-manager.js";
 import { installSkill } from "./writer.js";
-import { createDefaultSkillState, createDefaultSkillsManagerState, formatErr } from "./utils.js";
+import { createDefaultSkillState, createDefaultSkillsManagerState, formatErr, formatSkillVersions, joinSkillNames, } from "./utils.js";
+import { classifyInstallFailure, installRolledBack } from "./install-error.js";
+import { EVENT_NAME, eventAttrs } from "../utils/event-catalog.js";
+function emptyCheckRunSummary() {
+    return {
+        checked: 0,
+        upToDate: 0,
+        toInstall: [],
+        majorPending: [],
+        checkFailed: [],
+        installed: [],
+        installFailed: [],
+        onDisk: new Map(),
+    };
+}
 export class SkillsCoordinatorUnavailableError extends Error {
     constructor(message) {
         super(message);
@@ -109,10 +123,19 @@ export class SkillsUpdateCoordinator {
         this.state = await this.store.load();
         const bootstrapFn = this.options.deps?.bootstrapSkillsIfNeeded ?? bootstrapSkillsIfNeeded;
         try {
-            await bootstrapFn(config, logger);
+            const result = await bootstrapFn(config, logger);
+            if (result)
+                this.emitBootstrapEvents(result);
         }
         catch (err) {
             logger.warn("[senpi-skills-manager] bootstrap error (non-fatal)", err);
+            this.emitEvent(EVENT_NAME.skillsBootstrapCompleted, "warn", {
+                body: "Skills bootstrap errored before finishing",
+                attributes: eventAttrs({
+                    "senpi.skills.errored": true,
+                }),
+                error: err,
+            });
         }
         this.snapshot = this.buildSnapshot("healthy", "started");
     }
@@ -172,6 +195,13 @@ export class SkillsUpdateCoordinator {
             }
             catch (err) {
                 this.options.logger.warn("[senpi-skills-manager] tick error", err);
+                this.emitEvent(EVENT_NAME.skillsDegraded, "warn", {
+                    body: "Skills tick failed",
+                    attributes: eventAttrs({
+                        "senpi.skills.trigger": "tick",
+                    }),
+                    error: err,
+                });
                 this.snapshot = this.buildSnapshot("degraded", "tick-error", formatErr(err));
                 // No internal backoff — the next external tick (from auto-update's
                 // own poll loop / backoff) will retry on its own cadence.
@@ -217,6 +247,7 @@ export class SkillsUpdateCoordinator {
                 logger.warn(`[senpi-skills-manager] updateSkill — version check failed | skill=${skillName} err=${errorMessage}`);
                 this.recordCheckFailure(skillName, errorMessage);
                 await this.persistState();
+                this.emitCheckCompleted("update_skill", { ...emptyCheckRunSummary(), checked: 1, checkFailed: [skillName] });
                 this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-failed", errorMessage);
                 throw err;
             }
@@ -249,13 +280,26 @@ export class SkillsUpdateCoordinator {
                 // Persist so the `lastCheckedAt` timestamp survives a gateway restart
                 // even on skip paths (otherwise the next load() would see a stale null).
                 await this.persistState();
+                this.emitCheckCompleted("update_skill", {
+                    ...emptyCheckRunSummary(),
+                    checked: 1,
+                    upToDate: 1,
+                    onDisk: new Map([[skillName, versionInfo.localVersion]]),
+                });
                 // Refresh snapshot so the status RPC doesn't return pre-check data.
                 this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-skipped");
                 return { updated: false, version: versionInfo.localVersion };
             }
+            const runSummary = {
+                ...emptyCheckRunSummary(),
+                checked: 1,
+                toInstall: [skillName],
+                onDisk: new Map([[skillName, versionInfo.localVersion]]),
+            };
             try {
-                const installedVersion = await this.applyUpdate(skillName, versionInfo.remoteVersion);
+                const installedVersion = await this.applyUpdate(skillName, versionInfo);
                 logger.info(`[senpi-skills-manager] updateSkill complete | skill=${skillName} version=${installedVersion ?? "unknown"}`);
+                this.emitCheckCompleted("update_skill", { ...runSummary, installed: [skillName] });
                 // Refresh snapshot so the status RPC reflects the freshly-installed version
                 // immediately, rather than waiting for the next poll tick (up to 60 min).
                 this.snapshot = this.buildSnapshot("healthy", "manual-update-complete");
@@ -269,6 +313,7 @@ export class SkillsUpdateCoordinator {
                 // persist silently failed, and also so the updated lastCheckedAt we set
                 // earlier in this method is guaranteed to reach disk on the error path.
                 await this.persistState();
+                this.emitCheckCompleted("update_skill", { ...runSummary, installFailed: [skillName] });
                 this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-failed", errorMessage);
                 throw err;
             }
@@ -307,6 +352,8 @@ export class SkillsUpdateCoordinator {
             }));
             const results = [];
             const skillsToInstall = [];
+            const runSummary = { ...emptyCheckRunSummary(), checked: skillNames.length };
+            const checkedInfo = new Map();
             for (let index = 0; index < versionChecks.length; index++) {
                 const skillName = skillNames[index];
                 const checkResult = versionChecks[index];
@@ -319,10 +366,13 @@ export class SkillsUpdateCoordinator {
                     // the caller sees `error` in the returned array, but the snapshot
                     // and persisted state never reflect it.
                     this.recordCheckFailure(skillName, errorMessage);
+                    runSummary.checkFailed.push(skillName);
                     results.push({ name: skillName, updated: false, version: null, error: errorMessage });
                     continue;
                 }
                 const { localVersion, remoteVersion, updateKind } = checkResult.value;
+                checkedInfo.set(skillName, { localVersion, remoteVersion, updateKind });
+                runSummary.onDisk.set(skillName, localVersion);
                 // Mirror runTick: every successfully-checked skill gets `lastCheckedAt`
                 // updated and `installedVersion` refreshed from the local read, whether
                 // or not it proceeds to install. Otherwise skills touched only by
@@ -342,15 +392,18 @@ export class SkillsUpdateCoordinator {
                 if (updateKind === "none" || updateKind === "unknown") {
                     logger.info(`[senpi-skills-manager] updateAll — skipping | skill=${skillName} reason=${updateKind}`);
                     results.push({ name: skillName, updated: false, version: localVersion });
+                    runSummary.upToDate += 1;
                     continue;
                 }
                 skillsToInstall.push(skillName);
             }
+            runSummary.toInstall = [...skillsToInstall];
             if (skillsToInstall.length === 0) {
                 logger.info(`[senpi-skills-manager] updateAll complete — no installs needed | checked=${skillNames.length}`);
                 // Persist so the `lastCheckedAt` timestamps we just set on every
                 // successfully-checked skill survive a gateway restart.
                 await this.persistState();
+                this.emitCheckCompleted("update_all", runSummary);
                 // No installs, but we may have learned new remote versions from the
                 // parallel checks above — refresh the snapshot so getSnapshot() doesn't
                 // return pre-check data.
@@ -368,11 +421,14 @@ export class SkillsUpdateCoordinator {
                 logger.warn("[senpi-skills-manager] updateAll — clone failed", err);
                 for (const skillName of skillsToInstall) {
                     results.push({ name: skillName, updated: false, version: null, error: errorMessage });
+                    this.emitInstallFailed(skillName, "update_all", { failureKind: "clone", cause: err }, checkedInfo.get(skillName));
+                    runSummary.installFailed.push(skillName);
                 }
                 // Clone failure doesn't produce install outcomes per-skill, but every
                 // checked skill already had `lastCheckedAt` updated in-memory above.
                 // Persist so those timestamps survive a gateway restart.
                 await this.persistState();
+                this.emitCheckCompleted("update_all", runSummary);
                 this.snapshot = this.buildSnapshot(this.snapshot.health, "manual-update-clone-failed");
                 return results;
             }
@@ -380,16 +436,20 @@ export class SkillsUpdateCoordinator {
             let failureCount = 0;
             for (const skillName of skillsToInstall) {
                 const outcome = this.processInstallOutcome(skillName, installOutcomes);
+                this.emitInstallOutcome(skillName, "update_all", outcome, checkedInfo.get(skillName));
                 if (outcome.success) {
                     results.push({ name: skillName, updated: true, version: outcome.version });
+                    runSummary.installed.push(skillName);
                     successCount += 1;
                 }
                 else {
                     results.push({ name: skillName, updated: false, version: null, error: outcome.error });
+                    runSummary.installFailed.push(skillName);
                     failureCount += 1;
                 }
             }
             await this.persistState();
+            this.emitCheckCompleted("update_all", runSummary);
             logger.info(`[senpi-skills-manager] updateAll complete | installed=${successCount} failed=${failureCount} checked=${skillNames.length}`);
             // Refresh snapshot so the status RPC reflects the freshly-installed
             // versions immediately instead of waiting for the next poll tick.
@@ -459,19 +519,22 @@ export class SkillsUpdateCoordinator {
             // a major bump is authorized without re-resolving the source.
             return { name: skillName, ...versionInfo, maxMajor: source.maxMajor };
         }));
-        const skillsToInstall = [];
-        let majorPendingCount = 0;
-        let upToDateCount = 0;
+        // Triage results (up to date / held-back major / to install) accumulate on the summary.
+        const runSummary = { ...emptyCheckRunSummary(), checked: skillNames.length };
+        const checkedInfo = new Map();
         for (let index = 0; index < versionChecks.length; index++) {
             const skillName = skillNames[index];
             const checkResult = versionChecks[index];
             if (checkResult.status === "rejected") {
                 const errorMessage = formatErr(checkResult.reason);
                 this.recordCheckFailure(skillName, errorMessage);
+                runSummary.checkFailed.push(skillName);
                 logger.warn(`[senpi-skills-manager] tick — version check failed | skill=${skillName} err=${errorMessage}`);
                 continue;
             }
             const { localVersion, remoteVersion, updateKind, maxMajor } = checkResult.value;
+            checkedInfo.set(skillName, { localVersion, remoteVersion, updateKind });
+            runSummary.onDisk.set(skillName, localVersion);
             const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
             skillState.lastCheckedAt = new Date().toISOString();
             if (localVersion !== null)
@@ -487,7 +550,7 @@ export class SkillsUpdateCoordinator {
             logger.info(`[senpi-skills-manager] tick — skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} kind=${updateKind}`);
             if (updateKind === "none" || updateKind === "unknown") {
                 this.state.skills[skillName] = skillState;
-                upToDateCount += 1;
+                runSummary.upToDate += 1;
                 continue;
             }
             // Enforce the `maxMajor` ceiling on the **remote major regardless of how
@@ -502,54 +565,69 @@ export class SkillsUpdateCoordinator {
                 // `senpi skills update <name>` or by bumping `maxMajor` in the manifest.
                 logger.info(`[senpi-skills-manager] tick — major available, not auto-applied | skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} maxMajor=${maxMajor ?? "none"}`);
                 this.state.skills[skillName] = skillState;
-                majorPendingCount += 1;
+                runSummary.majorPending.push(skillName);
                 continue;
             }
             if (updateKind === "major") {
                 logger.info(`[senpi-skills-manager] tick — major within maxMajor ceiling, auto-applying | skill=${skillName} local=${localVersion ?? "none"} remote=${remoteVersion ?? "unknown"} maxMajor=${maxMajor}`);
             }
             // patch / minor / authorized-major — queue for install
-            skillsToInstall.push(skillName);
+            runSummary.toInstall.push(skillName);
             this.state.skills[skillName] = skillState;
         }
-        logger.info(`[senpi-skills-manager] tick — triage | upToDate=${upToDateCount} majorPending=${majorPendingCount} toInstall=${skillsToInstall.length}`);
-        if (skillsToInstall.length === 0)
-            return;
-        await this.applyUpdates(skillsToInstall);
+        logger.info(`[senpi-skills-manager] tick — triage | upToDate=${runSummary.upToDate} majorPending=${runSummary.majorPending.length} toInstall=${runSummary.toInstall.length}`);
+        if (runSummary.toInstall.length > 0) {
+            const applied = await this.applyUpdates([...runSummary.toInstall], checkedInfo);
+            runSummary.installed = applied.installed;
+            runSummary.installFailed = applied.failed;
+        }
+        // One summary per tick, after installs, so `installed_versions` is what the box has now. This is
+        // the regularly-emitted fact that answers "which version of each skill does this box run".
+        this.emitCheckCompleted("tick", runSummary);
     }
     /**
      * Clone the repo once and install every skill in `skillNames`.
      * Per-skill errors are recorded in state without aborting the others;
      * outcomes are logged (no notification).
      *
-     * If the clone itself fails we log and return without touching state — a
-     * full-clone failure is almost always a transient network/git issue that
-     * affects every skill equally. The next tick retries.
+     * A failed clone comes back from `withClonedGroups` as a per-skill `clone`
+     * outcome and is recorded like any other install failure. Only a throw from
+     * `cloneAndInstallMany` itself (the injected `cloneAndInstall` in tests)
+     * returns without touching state. The next tick retries either way.
      */
-    async applyUpdates(skillNames) {
+    async applyUpdates(skillNames, checkedInfo) {
         const { logger } = this.options;
         logger.info(`[senpi-skills-manager] applyUpdates — batch install starting | count=${skillNames.length} skills=${skillNames.join(",")}`);
+        const installed = [];
+        const failed = [];
         let installOutcomes;
         try {
             installOutcomes = await this.cloneAndInstallMany(skillNames);
         }
         catch (err) {
             logger.warn(`[senpi-skills-manager] applyUpdates — git clone failed, skipping batch: ${formatErr(err)}`);
-            return;
+            // Reached only when `cloneAndInstallMany` itself throws, which in tests means the injected
+            // `cloneAndInstall` dep. A real clone failure is caught per group in `withClonedGroups` and
+            // comes back as a `clone` outcome, which counts toward `consecutiveFailures` below.
+            for (const skillName of skillNames) {
+                this.emitInstallFailed(skillName, "tick", { failureKind: "clone", cause: err }, checkedInfo.get(skillName));
+                failed.push(skillName);
+            }
+            return { installed, failed };
         }
-        let succeeded = 0;
-        let failed = 0;
         for (const skillName of skillNames) {
             const outcome = this.processInstallOutcome(skillName, installOutcomes);
+            this.emitInstallOutcome(skillName, "tick", outcome, checkedInfo.get(skillName));
             if (outcome.success) {
-                succeeded += 1;
+                installed.push(skillName);
                 logger.info(`[senpi-skills-manager] applyUpdates — installed | skill=${skillName} version=${outcome.version ?? "unknown"}`);
             }
             else {
-                failed += 1;
+                failed.push(skillName);
             }
         }
-        logger.info(`[senpi-skills-manager] applyUpdates complete | installed=${succeeded} failed=${failed}`);
+        logger.info(`[senpi-skills-manager] applyUpdates complete | installed=${installed.length} failed=${failed.length}`);
+        return { installed, failed };
     }
     /**
      * Clone the remote skills repo exactly once and install every skill in
@@ -580,7 +658,12 @@ export class SkillsUpdateCoordinator {
                     });
                 }
                 else {
-                    outcomes.set(skillName, { version: null, error: "install failed" });
+                    outcomes.set(skillName, {
+                        version: null,
+                        error: "install failed",
+                        failureKind: "install",
+                        cause: new Error("install failed"),
+                    });
                 }
             }
             return outcomes;
@@ -617,7 +700,13 @@ export class SkillsUpdateCoordinator {
                 }
                 catch (err) {
                     const errorMessage = formatErr(err);
-                    outcomes.set(skillName, { version: null, error: errorMessage });
+                    outcomes.set(skillName, {
+                        version: null,
+                        error: errorMessage,
+                        failureKind: classifyInstallFailure(err),
+                        rolledBack: installRolledBack(err),
+                        cause: err,
+                    });
                     logger.warn(`[senpi-skills-manager] cloneAndInstallMany — install failed | skill=${skillName} err=${errorMessage}`);
                 }
             }
@@ -626,7 +715,7 @@ export class SkillsUpdateCoordinator {
             // and continues — earlier groups' installs are preserved.
             const errorMessage = `clone failed: ${formatErr(err)}`;
             for (const source of groupSources) {
-                outcomes.set(source.name, { version: null, error: errorMessage });
+                outcomes.set(source.name, { version: null, error: errorMessage, failureKind: "clone", cause: err });
             }
             logger.warn(`[senpi-skills-manager] cloneAndInstallMany — clone failed, skipping group | skills=${groupSources.map((s) => s.name).join(",")} err=${formatErr(err)}`);
         });
@@ -680,14 +769,25 @@ export class SkillsUpdateCoordinator {
      * success/failure result for the caller's bookkeeping.
      */
     processInstallOutcome(skillName, installOutcomes) {
-        const outcome = installOutcomes.get(skillName) ?? { version: null, error: "install result missing" };
+        const outcome = installOutcomes.get(skillName) ?? {
+            version: null,
+            error: "install result missing",
+            failureKind: "install",
+            cause: new Error("install result missing"),
+        };
         const skillState = this.state.skills[skillName] ?? createDefaultSkillState(skillName);
         if (outcome.error) {
             skillState.consecutiveFailures += 1;
             skillState.lastFailureAt = new Date().toISOString();
             skillState.lastFailureReason = outcome.error;
             this.state.skills[skillName] = skillState;
-            return { success: false, error: outcome.error };
+            return {
+                success: false,
+                error: outcome.error,
+                failureKind: outcome.failureKind,
+                cause: outcome.cause,
+                rolledBack: outcome.rolledBack,
+            };
         }
         this.recordSuccess(skillState, outcome.version);
         this.state.skills[skillName] = skillState;
@@ -702,8 +802,9 @@ export class SkillsUpdateCoordinator {
      * error is re-thrown here so `updateSkill` can surface it to the RPC
      * caller via a rejected promise (batch path captures it instead).
      */
-    async applyUpdate(skillName, remoteVersion) {
+    async applyUpdate(skillName, versionInfo) {
         const { logger } = this.options;
+        const { remoteVersion } = versionInfo;
         logger.info(`[senpi-skills-manager] applyUpdate — starting | skill=${skillName} targetVersion=${remoteVersion ?? "unknown"}`);
         // Clone can throw (full repo fetch failed). Unlike the batch path — which
         // intentionally doesn't attribute a shared clone failure to individual
@@ -724,6 +825,7 @@ export class SkillsUpdateCoordinator {
             this.state.skills[skillName] = skillState;
             await this.persistState();
             logger.warn(`[senpi-skills-manager] applyUpdate — ${errorMessage} | skill=${skillName}`);
+            this.emitInstallFailed(skillName, "update_skill", { failureKind: "clone", cause: err }, versionInfo);
             throw err;
         }
         // Delegate outcome bookkeeping (success or install-failure) to the shared
@@ -733,6 +835,7 @@ export class SkillsUpdateCoordinator {
         // updateSkill install failures were silently invisible to the snapshot.
         const processed = this.processInstallOutcome(skillName, installOutcomes);
         await this.persistState();
+        this.emitInstallOutcome(skillName, "update_skill", processed, versionInfo);
         if (!processed.success) {
             logger.warn(`[senpi-skills-manager] applyUpdate — install failed | skill=${skillName} err=${processed.error}`);
             throw new Error(processed.error);
@@ -827,6 +930,191 @@ export class SkillsUpdateCoordinator {
             skills: skillSnapshots,
         };
     }
+    // ── Telemetry (`skills.*` events) ─────────────────────────────────────────
+    // Emit-only: none of these read back into decisions or state.
+    /**
+     * Skills whose failed install could not put the previous install back (`rolled_back=false`), so
+     * the skill dir is gone. Filled by `emitInstallFailed`, read and cleared by the next
+     * `emitCheckCompleted`. Runs are serialized on `operationChain`, so one run never sees another's.
+     */
+    skillDirsLost = new Set();
+    /**
+     * What the last check run in this process saw on disk, per skill (`null` = nothing there). A run
+     * that checks only some skills (`updateSkill`) reports the rest from here, not from persisted
+     * state, which keeps the last non-null version.
+     */
+    lastOnDisk = new Map();
+    /**
+     * Emit a catalogued `skills.*` event, guarded so a throwing sink or a bad attribute shape can
+     * never disturb a tick, a manual update or bootstrap.
+     */
+    emitEvent(name, level, opts) {
+        try {
+            this.options.logger.event(name, level, opts);
+        }
+        catch {
+            // A telemetry-side failure must never disturb the skills-manager.
+        }
+    }
+    /** `skills.check_completed`: one summary per check run, with the whole managed set's versions. */
+    emitCheckCompleted(trigger, summary) {
+        let managed;
+        try {
+            managed = this.resolveSkillNames();
+        }
+        catch {
+            // Telemetry must not throw. The check itself already resolved the set, so this does not happen.
+            managed = Object.keys(this.state.skills);
+        }
+        // A skill not checked in this run reads as the last run saw it on disk. Then record what this
+        // run leaves on disk, for the next run.
+        for (const name of managed) {
+            if (!summary.onDisk.has(name) && this.lastOnDisk.has(name)) {
+                summary.onDisk.set(name, this.lastOnDisk.get(name) ?? null);
+            }
+        }
+        for (const name of managed) {
+            if (summary.installed.includes(name)) {
+                this.lastOnDisk.set(name, this.state.skills[name]?.installedVersion ?? null);
+            }
+            else if (summary.installFailed.includes(name) && this.skillDirsLost.has(name)) {
+                this.lastOnDisk.set(name, null);
+            }
+            else if (summary.onDisk.has(name)) {
+                this.lastOnDisk.set(name, summary.onDisk.get(name) ?? null);
+            }
+        }
+        // What is on disk now, per skill: the version installed in this run; else nothing, when this
+        // run's install failed and could not put the previous install back; else the version read from
+        // disk in this run (null = nothing readable); else, for a skill not checked in this run, the
+        // persisted version. Persisted state is not cleared on a null read, so it alone would report a
+        // vanished skill dir at its old version.
+        const lostNow = (name) => summary.installFailed.includes(name) && this.skillDirsLost.has(name);
+        const installedNow = (name) => {
+            if (summary.installed.includes(name))
+                return this.state.skills[name]?.installedVersion ?? null;
+            if (lostNow(name))
+                return null;
+            if (summary.onDisk.has(name))
+                return summary.onDisk.get(name) ?? null;
+            return this.state.skills[name]?.installedVersion ?? null;
+        };
+        const missing = managed.filter((name) => !summary.installed.includes(name) &&
+            (lostNow(name) || (summary.onDisk.has(name) && summary.onDisk.get(name) === null)));
+        const installedVersions = formatSkillVersions(managed.map((name) => [name, installedNow(name)]));
+        this.skillDirsLost.clear();
+        const latestVersions = formatSkillVersions(managed.map((name) => [
+            name,
+            this.latestVersions.get(name) ?? this.state.skills[name]?.latestVersion,
+        ]));
+        this.emitEvent(EVENT_NAME.skillsCheckCompleted, "info", {
+            body: `Skills check (${trigger}): checked=${summary.checked} upToDate=${summary.upToDate} ` +
+                `toInstall=${summary.toInstall.length} majorPending=${summary.majorPending.length} ` +
+                `checkFailed=${summary.checkFailed.length} missing=${missing.length} ` +
+                `installed=${summary.installed.length} installFailed=${summary.installFailed.length}`,
+            attributes: eventAttrs({
+                "senpi.skills.trigger": trigger,
+                "senpi.skills.checked_count": summary.checked,
+                "senpi.skills.up_to_date_count": summary.upToDate,
+                "senpi.skills.to_install_count": summary.toInstall.length,
+                "senpi.skills.major_pending_count": summary.majorPending.length,
+                "senpi.skills.check_failed_count": summary.checkFailed.length,
+                "senpi.skills.missing_count": missing.length,
+                "senpi.skills.installed_count": summary.installed.length,
+                "senpi.skills.install_failed_count": summary.installFailed.length,
+                "senpi.skills.installed_versions": installedVersions,
+                "senpi.skills.latest_versions": latestVersions,
+                "senpi.skills.to_install": joinSkillNames(summary.toInstall),
+                "senpi.skills.major_pending": joinSkillNames(summary.majorPending),
+                "senpi.skills.check_failed": joinSkillNames(summary.checkFailed),
+                "senpi.skills.missing": joinSkillNames(missing),
+            }),
+        });
+    }
+    /** `skills.installed` or `skills.install_failed` for one processed install outcome. */
+    emitInstallOutcome(skillName, trigger, outcome, info) {
+        if (!outcome.success) {
+            this.emitInstallFailed(skillName, trigger, outcome, info);
+            return;
+        }
+        this.emitInstalled(skillName, trigger, {
+            fromVersion: info?.localVersion ?? null,
+            toVersion: outcome.version ?? info?.remoteVersion ?? null,
+            updateKind: info?.updateKind ?? null,
+        });
+    }
+    emitInstalled(skillName, trigger, versions) {
+        const source = this.resolveSourceForTelemetry(skillName);
+        this.emitEvent(EVENT_NAME.skillsInstalled, "info", {
+            body: `Skill ${skillName} installed (${trigger}): ${versions.fromVersion ?? "none"} -> ${versions.toVersion ?? "unknown"}`,
+            attributes: eventAttrs({
+                "senpi.skills.skill": skillName,
+                "senpi.skills.trigger": trigger,
+                "senpi.skills.from_version": versions.fromVersion ?? undefined,
+                "senpi.skills.to_version": versions.toVersion ?? undefined,
+                "senpi.skills.update_kind": versions.updateKind ?? undefined,
+                "senpi.skills.source_branch": source?.branch,
+                "senpi.skills.preserve_paths_count": source?.preserve.length ?? 0,
+            }),
+        });
+    }
+    /** `skills.install_failed`. The original thrown value rides the `error` slot, stack and all. */
+    emitInstallFailed(skillName, trigger, failure, info) {
+        if (failure.rolledBack === false)
+            this.skillDirsLost.add(skillName);
+        else
+            this.skillDirsLost.delete(skillName);
+        const source = this.resolveSourceForTelemetry(skillName);
+        // Bootstrap keeps no per-skill failure state, so it has no running count to report.
+        const consecutiveFailures = trigger === "bootstrap" ? undefined : this.state.skills[skillName]?.consecutiveFailures;
+        this.emitEvent(EVENT_NAME.skillsInstallFailed, "error", {
+            body: `Skill ${skillName} install failed (${trigger}, ${failure.failureKind})`,
+            attributes: eventAttrs({
+                "senpi.skills.skill": skillName,
+                "senpi.skills.trigger": trigger,
+                "senpi.skills.failure_kind": failure.failureKind,
+                "senpi.skills.rolled_back": failure.rolledBack,
+                "senpi.skills.consecutive_failures": consecutiveFailures,
+                "senpi.skills.from_version": info?.localVersion ?? undefined,
+                "senpi.skills.to_version": info?.remoteVersion ?? undefined,
+                "senpi.skills.update_kind": info?.updateKind,
+                "senpi.skills.source_branch": source?.branch,
+            }),
+            error: failure.cause,
+        });
+    }
+    /** `skills.bootstrap_completed` plus one `skills.installed` / `skills.install_failed` per attempt. */
+    emitBootstrapEvents(result) {
+        for (const name of result.installed) {
+            this.emitInstalled(name, "bootstrap", { fromVersion: null, toVersion: null, updateKind: null });
+        }
+        for (const failure of result.failed) {
+            this.emitInstallFailed(failure.name, "bootstrap", failure, undefined);
+        }
+        this.emitEvent(EVENT_NAME.skillsBootstrapCompleted, result.failed.length > 0 ? "warn" : "info", {
+            body: `Skills bootstrap: manifest=${result.manifestCount} missing=${result.missing.length} ` +
+                `installed=${result.installed.length} failed=${result.failed.length}`,
+            attributes: eventAttrs({
+                "senpi.skills.errored": false,
+                "senpi.skills.manifest_count": result.manifestCount,
+                "senpi.skills.missing_count": result.missing.length,
+                "senpi.skills.installed_count": result.installed.length,
+                "senpi.skills.install_failed_count": result.failed.length,
+                "senpi.skills.missing": joinSkillNames(result.missing),
+                "senpi.skills.installed": joinSkillNames(result.installed),
+                "senpi.skills.install_failed": joinSkillNames(result.failed.map((f) => f.name)),
+            }),
+        });
+    }
+    /** Source for event attrs only; a resolve failure drops the source attrs instead of throwing. */
+    resolveSourceForTelemetry(skillName) {
+        try {
+            return this.resolveSource(skillName);
+        }
+        catch {
+            return null;
+        }
+    }
     async persistState() {
         try {
             await this.store.save(this.state);