fix(skills): refresh snapshots when watch roots change

hclsys · hclsys · commit aa0a569c0248 · 2026-05-19T07:13:10.000+08:00
diff --git a/src/agents/skills/refresh-state.ts b/src/agents/skills/refresh-state.ts
@@ -1,6 +1,6 @@
 export type SkillsChangeEvent = {
   workspaceDir?: string;
-  reason: "watch" | "manual" | "remote-node" | "config-change";
+  reason: "watch" | "watch-targets" | "manual" | "remote-node" | "config-change";
   changedPath?: string;
 };
 
diff --git a/src/agents/skills/refresh.test.ts b/src/agents/skills/refresh.test.ts
@@ -151,4 +151,30 @@ describe("ensureSkillsWatcher", () => {
       ]);
     },
   );
+
+  it("refreshes skills snapshots when watched skill roots change", () => {
+    const seen: SkillsChangeEvent[] = [];
+    refreshModule.registerSkillsChangeListener((change) => {
+      seen.push(change);
+    });
+    refreshModule.ensureSkillsWatcher({
+      workspaceDir: "/tmp/workspace",
+      config: { skills: { load: { extraDirs: ["/tmp/shared-a"] } } },
+    });
+
+    refreshModule.ensureSkillsWatcher({
+      workspaceDir: "/tmp/workspace",
+      config: { skills: { load: { extraDirs: ["/tmp/shared-b"] } } },
+    });
+
+    expect(watchMock).toHaveBeenCalledTimes(2);
+    expect(createdWatchers[0]?.close).toHaveBeenCalledTimes(1);
+    expect(seen).toEqual([
+      {
+        workspaceDir: "/tmp/workspace",
+        reason: "watch-targets",
+        changedPath: expect.stringContaining("/tmp/shared-b"),
+      },
+    ]);
+  });
 });
diff --git a/src/agents/skills/refresh.ts b/src/agents/skills/refresh.ts
@@ -127,6 +127,7 @@ export function ensureSkillsWatcher(params: { workspaceDir: string; config?: Ope
   if (existing && existing.pathsKey === pathsKey && existing.debounceMs === debounceMs) {
     return;
   }
+  const watchTargetsChanged = existing ? existing.pathsKey !== pathsKey : false;
   if (existing) {
     watchers.delete(workspaceDir);
     if (existing.timer) {
@@ -174,6 +175,13 @@ export function ensureSkillsWatcher(params: { workspaceDir: string; config?: Ope
   });
 
   watchers.set(workspaceDir, state);
+  if (watchTargetsChanged) {
+    bumpSkillsSnapshotVersion({
+      workspaceDir,
+      reason: "watch-targets",
+      changedPath: pathsKey,
+    });
+  }
 }
 
 export async function resetSkillsRefreshForTest(): Promise<void> {
diff --git a/src/auto-reply/reply/session-updates.test.ts b/src/auto-reply/reply/session-updates.test.ts
@@ -37,7 +37,7 @@ const {
   })),
   ensureSkillsWatcherMock: vi.fn(),
   getSkillsSnapshotVersionMock: vi.fn(() => 0),
-  shouldRefreshSnapshotForVersionMock: vi.fn(() => false),
+  shouldRefreshSnapshotForVersionMock: vi.fn((_cached?: number, _next?: number) => false),
   getRemoteSkillEligibilityMock: vi.fn(() => ({
     platforms: [],
     hasBin: () => false,
@@ -59,6 +59,9 @@ vi.mock("../../agents/skills.js", () => ({
 
 vi.mock("../../agents/skills/refresh.js", () => ({
   ensureSkillsWatcher: ensureSkillsWatcherMock,
+}));
+
+vi.mock("../../agents/skills/refresh-state.js", () => ({
   getSkillsSnapshotVersion: getSkillsSnapshotVersionMock,
   shouldRefreshSnapshotForVersion: shouldRefreshSnapshotForVersionMock,
 }));
@@ -197,6 +200,31 @@ describe("ensureSkillSnapshot", () => {
     expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledTimes(2);
   });
 
+  it("reads the skills snapshot version after watcher-side invalidation", async () => {
+    vi.stubEnv("OPENCLAW_TEST_FAST", "0");
+    getSkillsSnapshotVersionMock.mockReturnValue(0);
+    ensureSkillsWatcherMock.mockImplementation(() => {
+      getSkillsSnapshotVersionMock.mockReturnValue(5);
+    });
+    shouldRefreshSnapshotForVersionMock.mockImplementation((cached = 0, next = 0) => cached < next);
+
+    await ensureSkillSnapshot({
+      sessionEntry: testSessionEntry("sess-1", strippedSnapshot()),
+      sessionStore: {},
+      sessionKey: "main",
+      isFirstTurnInSession: false,
+      workspaceDir: TEST_WORKSPACE_DIR,
+      cfg: { skills: { load: { extraDirs: ["/tmp/shared-skills"] } } },
+    });
+
+    expect(shouldRefreshSnapshotForVersionMock).toHaveBeenCalledWith(0, 5);
+    expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledTimes(1);
+    const [[, snapshotParams]] = buildWorkspaceSkillSnapshotMock.mock.calls as unknown as Array<
+      [string, { snapshotVersion?: number }]
+    >;
+    expect(snapshotParams.snapshotVersion).toBe(5);
+  });
+
   it("invalidates cache when non-skills config gates change", async () => {
     vi.stubEnv("OPENCLAW_TEST_FAST", "0");
 
diff --git a/src/auto-reply/reply/session-updates.ts b/src/auto-reply/reply/session-updates.ts
@@ -259,9 +259,9 @@ export async function ensureSkillSnapshot(params: {
       agentId: sessionAgentId,
     }),
   });
-  const snapshotVersion = getSkillsSnapshotVersion(workspaceDir);
   const existingSnapshot = nextEntry?.skillsSnapshot;
   ensureSkillsWatcher({ workspaceDir, config: cfg });
+  const snapshotVersion = getSkillsSnapshotVersion(workspaceDir);
   const shouldRefreshSnapshot =
     shouldRefreshSnapshotForVersion(existingSnapshot?.version, snapshotVersion) ||
     !matchesSkillFilter(existingSnapshot?.skillFilter, skillFilter);
