@@ -24,6 +24,16 @@ export class SkillsManager {
2424 private disposables : vscode . Disposable [ ] = [ ]
2525 private isDisposed = false
2626
27+ /**
28+ * Monotonic token identifying the current discovery run. Each call to
29+ * {@link discoverSkills} bumps this value; the running scan captures it and
30+ * bails out (without mutating {@link skills}) once a newer run starts or the
31+ * manager is disposed. This keeps the recursive, asynchronous scan
32+ * lifecycle-aware so a stale traversal cannot repopulate a disposed or
33+ * superseded manager.
34+ */
35+ private discoveryGeneration = 0
36+
2737 constructor ( provider : ClineProvider ) {
2838 this . providerRef = new WeakRef ( provider )
2939 }
@@ -41,21 +51,100 @@ export class SkillsManager {
4151 * - .roo/skills/[dirname] can be a symlink to a skill directory
4252 */
4353 async discoverSkills ( ) : Promise < void > {
54+ // Start a new discovery generation. Any previously running scan captured
55+ // an older token and will stop mutating state once it notices the change.
56+ const generation = ++ this . discoveryGeneration
4457 this . skills . clear ( )
4558 const skillsDirs = await this . getSkillsDirectories ( )
4659
4760 for ( const { dir, source, mode } of skillsDirs ) {
48- await this . scanSkillsDirectory ( dir , source , mode )
61+ // Abort early if this run was superseded or the manager was disposed
62+ // while awaiting the directory list.
63+ if ( ! this . isCurrentGeneration ( generation ) ) {
64+ return
65+ }
66+ // Use a fresh visited set and a fresh set of approved real roots for
67+ // each top-level scan so traversal is deduplicated within a single
68+ // root without sharing state across different source or mode roots.
69+ await this . scanSkillsDirectory ( dir , source , mode , generation , 0 , new Set < string > ( ) , new Set < string > ( ) )
70+ }
71+ }
72+
73+ /**
74+ * Whether the given discovery token still identifies the active run. Returns
75+ * false once a newer {@link discoverSkills} call starts or the manager is
76+ * disposed, allowing an in-flight recursive scan to bail out without
77+ * repopulating a disposed or superseded manager.
78+ */
79+ private isCurrentGeneration ( generation : number ) : boolean {
80+ return ! this . isDisposed && generation === this . discoveryGeneration
81+ }
82+
83+ /**
84+ * Maximum depth for recursive scanning of symlinked skill container directories.
85+ * Prevents infinite loops from circular symlinks.
86+ */
87+ private static readonly MAX_SCAN_DEPTH = 5
88+
89+ /**
90+ * Determine whether a resolved real path is contained within one of the
91+ * approved real roots (i.e., equal to a root or nested beneath it).
92+ *
93+ * This is the trust boundary that keeps deep recursion from following a
94+ * nested symlink out to an unrelated directory. Comparison is done against
95+ * already-resolved real paths, so a symlink target that resolves outside
96+ * every approved root is rejected.
97+ */
98+ private isContainedWithinApprovedRoot ( realPath : string , approvedRoots : Set < string > ) : boolean {
99+ for ( const root of approvedRoots ) {
100+ if ( realPath === root ) {
101+ return true
102+ }
103+ // Ensure a true path-segment boundary (root + separator) so that
104+ // e.g. "/a/skills-private" is not treated as inside "/a/skills".
105+ const rootWithSep = root . endsWith ( path . sep ) ? root : root + path . sep
106+ if ( realPath . startsWith ( rootWithSep ) ) {
107+ return true
108+ }
49109 }
110+ return false
50111 }
51112
52113 /**
53114 * Scan a skills directory for skill subdirectories.
54- * Handles two symlink cases:
115+ * Handles symlink cases:
55116 * 1. The skills directory itself is a symlink (resolved by directoryExists using realpath)
56117 * 2. Individual skill subdirectories are symlinks
118+ * 3. Symlinked container directories that contain skill subdirectories (e.g., ln -s ../../repo/skills .roo/skills/)
119+ *
120+ * Trust boundary: the explicitly configured skills root (and the first-level
121+ * entries placed directly inside it) are the approved real roots. Deeper
122+ * directories are only scanned or loaded when their resolved real path stays
123+ * within one of those approved roots. This prevents a nested symlink inside
124+ * an already-followed container from escaping to an unrelated directory.
125+ *
126+ * @param approvedRoots - Set of resolved real paths that bound traversal.
127+ * Empty on the initial (depth 0) call; it is seeded with the configured
128+ * root's real path and each first-level entry's real path.
57129 */
58- private async scanSkillsDirectory ( dirPath : string , source : "global" | "project" , mode ?: string ) : Promise < void > {
130+ private async scanSkillsDirectory (
131+ dirPath : string ,
132+ source : "global" | "project" ,
133+ mode : string | undefined ,
134+ generation : number ,
135+ depth : number = 0 ,
136+ visited : Set < string > = new Set < string > ( ) ,
137+ approvedRoots : Set < string > = new Set < string > ( ) ,
138+ ) : Promise < void > {
139+ if ( depth > SkillsManager . MAX_SCAN_DEPTH ) {
140+ return
141+ }
142+
143+ // Bail out if this scan was superseded or the manager was disposed.
144+ if ( ! this . isCurrentGeneration ( generation ) ) {
145+ return
146+ }
147+
59148 if ( ! ( await directoryExists ( dirPath ) ) ) {
60149 return
61150 }
@@ -64,18 +153,73 @@ export class SkillsManager {
64153 // Get the real path (resolves if dirPath is a symlink)
65154 const realDirPath = await fs . realpath ( dirPath )
66155
156+ // The configured skills root is trusted by definition, even if it is
157+ // itself a symlink to an external location. Seed the approved roots
158+ // with its real path on the initial scan.
159+ if ( depth === 0 ) {
160+ approvedRoots . add ( realDirPath )
161+ }
162+
163+ // Skip directories we've already visited (by real path) to avoid
164+ // redundant scanning and infinite loops from circular symlinks.
165+ if ( visited . has ( realDirPath ) ) {
166+ return
167+ }
168+ visited . add ( realDirPath )
169+
67170 // Read directory entries
68171 const entries = await fs . readdir ( realDirPath )
69172
70173 for ( const entryName of entries ) {
174+ // Stop mutating state if a newer scan started or we were disposed
175+ // while awaiting earlier filesystem operations in this loop.
176+ if ( ! this . isCurrentGeneration ( generation ) ) {
177+ return
178+ }
179+
71180 const entryPath = path . join ( realDirPath , entryName )
72181
73182 // Check if this entry is a directory (follows symlinks automatically)
74183 const stats = await fs . stat ( entryPath ) . catch ( ( ) => null )
75184 if ( ! stats ?. isDirectory ( ) ) continue
76185
77- // Load skill metadata - the skill name comes from the entry name (symlink name if symlinked)
78- await this . loadSkillMetadata ( entryPath , source , mode , entryName )
186+ // Resolve the entry's real path so containment is checked against
187+ // the symlink target rather than the (possibly symlinked) name.
188+ const realEntryPath = await fs . realpath ( entryPath ) . catch ( ( ) => null )
189+ if ( ! realEntryPath ) continue
190+
191+ // First-level entries live directly inside the configured root, so
192+ // they (and their targets) are trusted as approved roots. This
193+ // preserves support for a symlinked container placed directly under
194+ // .roo/skills (e.g., ln -s ../../repo/skills .roo/skills/).
195+ if ( depth === 0 ) {
196+ approvedRoots . add ( realEntryPath )
197+ } else if ( ! this . isContainedWithinApprovedRoot ( realEntryPath , approvedRoots ) ) {
198+ // A deeper entry that resolves outside every approved root is a
199+ // nested symlink escaping the trust boundary - skip it.
200+ continue
201+ }
202+
203+ // Check if this directory contains a SKILL.md (i.e., it's a skill directory)
204+ const skillMdPath = path . join ( entryPath , "SKILL.md" )
205+ if ( await fileExists ( skillMdPath ) ) {
206+ // Load skill metadata - the skill name comes from the entry name (symlink name if symlinked)
207+ await this . loadSkillMetadata ( entryPath , source , mode , generation , entryName )
208+ } else {
209+ // No SKILL.md found - this might be a container directory (e.g., a symlinked repo of skills)
210+ // Recursively scan it for skill subdirectories, sharing the same
211+ // visited set and approved roots so traversal stays deduplicated
212+ // and bounded within this scan.
213+ await this . scanSkillsDirectory (
214+ entryPath ,
215+ source ,
216+ mode ,
217+ generation ,
218+ depth + 1 ,
219+ visited ,
220+ approvedRoots ,
221+ )
222+ }
79223 }
80224 } catch {
81225 // Directory doesn't exist or can't be read - this is fine
@@ -87,12 +231,14 @@ export class SkillsManager {
87231 * @param skillDir - The resolved path to the skill directory (target of symlink if symlinked)
88232 * @param source - Whether this is a global or project skill
89233 * @param mode - The mode this skill is specific to (undefined for generic skills)
234+ * @param generation - The discovery generation token for the active scan
90235 * @param skillName - The skill name (from symlink name if symlinked, otherwise from directory name)
91236 */
92237 private async loadSkillMetadata (
93238 skillDir : string ,
94239 source : "global" | "project" ,
95- mode ?: string ,
240+ mode : string | undefined ,
241+ generation : number ,
96242 skillName ?: string ,
97243 ) : Promise < void > {
98244 const skillMdPath = path . join ( skillDir , "SKILL.md" )
@@ -162,6 +308,13 @@ export class SkillsManager {
162308 const primaryMode = modeSlugs ?. [ 0 ]
163309 const skillKey = this . getSkillKey ( effectiveSkillName , source , primaryMode )
164310
311+ // Do not repopulate a disposed or superseded manager: bail out if a
312+ // newer discovery run started (or dispose ran) while we were reading
313+ // and parsing this skill's SKILL.md.
314+ if ( ! this . isCurrentGeneration ( generation ) ) {
315+ return
316+ }
317+
165318 this . skills . set ( skillKey , {
166319 name : effectiveSkillName ,
167320 description,
@@ -712,6 +865,9 @@ Add your skill instructions here.
712865
713866 async dispose ( ) : Promise < void > {
714867 this . isDisposed = true
868+ // Invalidate any in-flight discovery so a stale recursive scan cannot
869+ // repopulate the map after disposal.
870+ this . discoveryGeneration ++
715871 this . disposables . forEach ( ( d ) => d . dispose ( ) )
716872 this . disposables = [ ]
717873 this . skills . clear ( )
0 commit comments