fix(skills): refresh snapshots when watch roots change (#83823)

clawsweeper[bot] · hclsys · Takhoffman · web-flow · commit f1a55cbd5203 · 2026-05-19T00:36:27.000Z
Summary: - The replacement PR adds a `watch-targets` skills snapshot invalidation when `ensureSkillsWatcher` rebuilds f ... root set, reads the snapshot version after watcher setup, adds regression tests, and updates the changelog. - Reproducibility: yes. Source inspection shows current main rebuilds the skills watcher on changed root targe ... the version before watcher setup; I did not run a live Gateway mount reproduction in this read-only review. Automerge notes: - PR branch already contained follow-up commit before automerge: fix(skills): refresh snapshots when watch roots change Validation: - ClawSweeper review passed for head 2677dcc. - Required merge gates passed before the squash merge. Prepared head SHA: 2677dcc Review: #83823 (comment) Co-authored-by: hclsys <hclsys@openclaw.ai> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -53,6 +53,7 @@ Docs: https://docs.openclaw.ai
 - CLI/update: bypass npm freshness filters consistently during managed package and plugin installs so freshly published release plugins remain installable. Thanks @jalehman.
 - CLI/update: guide root-owned npm install EACCES recovery by stopping the managed Gateway before manual package replacement, then reinstalling and restarting the service. Fixes #83747. (#83757) Thanks @brokemac79.
 - Agents/subagents: keep collect-mode announce queues batching unresolved-origin items with compatible same-route messages and resume collection after a true cross-channel drain when a later compatible batch remains. Fixes #83577.
+- Skills: refresh existing session skill snapshots when watched skill roots change, so changed extra skill directories take effect without starting a new session. Fixes #83782. (#83800) Thanks @hclsys.
 - Providers/Anthropic: preserve native image input for current Claude model rows when stale local catalog data marks them text-only. (#83756) Thanks @TurboTheTurtle.
 - Control UI: render live tool progress from session-scoped `session.tool` Gateway events so externally started runs show their tool cards in the active session. (#83734) Thanks @TurboTheTurtle.
 - Outbound: resolve send-capable channel plugins from the active runtime registry when the pinned startup registry only has setup metadata. (#83733) Thanks @TurboTheTurtle.
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);
