@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/skills/manager.js

@@ -0,0 +1,1386 @@
+/**
+ * `SkillsManager`.
+ *
+ * Walks every configured source, parses + validates each `SKILL.md`, then
+ * builds an in-memory catalog keyed by fully-qualified
+ * `<vendor>/<name>@<version>` with shadowing.
+ *
+ * Construction is synchronous and cheap (validate config, store). The
+ * `discover()` method does the disk IO; it's idempotent — subsequent
+ * calls return the same already-built catalog. Public lookups via
+ * `list()` / `get()` await discovery completion implicitly.
+ *
+ * Invariants:
+ *   - Catalog is built once per discovery; hot reload reruns discovery
+ *     to produce a fresh snapshot.
+ *   - Trust tier is derived from source type only; consumer-supplied
+ *     `trustedSources` is used to elevate third-party sources.
+ *   - Per-skill `min_sdk_version` exclusion lands here.
+ */
+import { promises as fs, watch as fsWatch } from 'node:fs';
+import * as path from 'node:path';
+import { parseSkillDocument, SkillParseError } from './parser.js';
+import { defaultWalkerEnv, walkSource } from './sources/index.js';
+import { safeRealPath } from './sources/walk.js';
+import { isSkillTrusted, validateTrustedSources } from './trust.js';
+import { findLockfile, LockfileValidationError, loadLockfile, validateLockfileEntry, } from './lockfile.js';
+import { DEFAULT_SOURCE_ORDER, REQUIRES_DEFAULT_MAX_DEPTH, REQUIRES_DEFAULT_MAX_TRANSITIVE, REQUIRES_DEFAULT_MAX_TRANSITIVE_TOKENS, SKILL_FILE_HARD_BYTES, SOURCE_DEFAULT_VENDORS, SOURCE_TRUST_TIERS, } from './types.js';
+import { extractBodyReferences, semverLessThan, validateBody, validateFrontmatter, } from './validator.js';
+/** Default `version` when frontmatter omits it. */
+const DEFAULT_VERSION = '0.0.0';
+export class SkillsManager {
+    config;
+    env;
+    emit;
+    trustedSourceIdentities;
+    requiresCaps;
+    /**
+     * Per-client active-skill set. Populated by caller-pin activation
+     * (`TaskClient`) and by LLM-driven `get_skill` calls (the MCP server,
+     * via `markLoaded`). Cleared by `resetActive()`.
+     *
+     * SDK 2.0 has no per-task AsyncLocalStorage env-scope (the design that
+     * shipped on SDK 1.x's `EnvironmentServices`); active-state lives on
+     * the manager, scoped to the client lifetime. Concurrent dispatches
+     * against the same client observe a merged set — documented in the
+     * architectural-translation note. `disconnect()` calls
+     * `skillsMcpServer.dispose()` which calls `resetActive()` (transitively
+     * through the existing `activeFqns` clear), so a fresh `connect()`
+     * starts cold.
+     */
+    activeFqns = new Set();
+    discoverPromise = null;
+    snapshot = null;
+    /**
+     * Active `fs.watch` handles keyed by the absolute directory path
+     * being watched. Populated by `startWatching()`, cleared by
+     * `stopWatching()` / `dispose()`.
+     */
+    watchers = new Map();
+    /** Pending watcher-triggered rebuild timer, debounced. */
+    rebuildTimer = null;
+    /** Promise that resolves with the next rebuilt snapshot, if a rebuild is in-flight. */
+    rebuildPromise = null;
+    /** Optional listener fired after every successful rebuild — used by tests / consumers. */
+    rebuildListeners = new Set();
+    epoch = 0;
+    /**
+     * In-flight `startWatching()` promise. Concurrent calls await the
+     * same promise so the install pass is serialised — defends against
+     * the watcher-duplication race when auto-start + manual start fire
+     * close together.
+     */
+    startWatchingPromise = null;
+    /**
+     * Marks that a watcher event arrived while a rebuild was already
+     * in flight. The current rebuild's `.then` re-schedules so the late
+     * change isn't dropped.
+     */
+    pendingRebuild = false;
+    constructor(config, env = defaultWalkerEnv()) {
+        this.config = config;
+        this.env = env;
+        this.emit = config.emit;
+        // Validate `trustedSources` against the configured `sources` list at
+        // construction time so a misconfigured allowlist fails loud at `new
+        // QodoClient({ skills: {...} })` instead of at the first activation
+        // attempt.
+        const sources = this.resolveSourcesList();
+        this.trustedSourceIdentities = validateTrustedSources(config.trustedSources, sources);
+        this.requiresCaps = resolveRequiresCaps(config.requires);
+    }
+    /**
+     * Forward a renderer-produced event batch to the configured sink.
+     * Used by `TaskClient`'s skills injection helpers — the renderer is
+     * pure and returns events as data; the manager owns the sink wiring
+     * so consumers see one consistent emission surface.
+     */
+    forwardEvents(events) {
+        for (const event of events)
+            this.emitEvent(event);
+    }
+    /**
+     * Walk every configured source, parse + validate, build the FQN-keyed
+     * catalog. Idempotent — concurrent calls share one in-flight promise.
+     */
+    discover() {
+        if (this.snapshot !== null)
+            return Promise.resolve(this.snapshot);
+        if (this.discoverPromise !== null)
+            return this.discoverPromise;
+        this.discoverPromise = this.doRebuild('initial_discover').then((snapshot) => {
+            if (this.config.watch === true) {
+                // Fire-and-forget — watcher installation reads the now-set
+                // `snapshot.bySource`; failures emit `sdk.skill.error`.
+                this.startWatching().catch(() => {
+                    // ignored — startWatching surfaces errors through emitEvent
+                });
+            }
+            return snapshot;
+        });
+        return this.discoverPromise;
+    }
+    /** Resolved `true` once `discover()` has completed at least once. */
+    get isReady() {
+        return this.snapshot !== null;
+    }
+    /** Synchronous snapshot accessor. Returns `null` until `discover()` resolves. */
+    get currentSnapshot() {
+        return this.snapshot;
+    }
+    /**
+     * Constructor-supplied default `activate` set. `TaskClient` reads this
+     * when the per-call `opts.skills` is `undefined`. Returned read-only;
+     * `[]` and `undefined` are distinct (`[]` = explicit empty, `undefined`
+     * = "no default set").
+     */
+    get defaultActivate() {
+        return this.config.activate;
+    }
+    /**
+     * Constructor-supplied `indexCharBudget`. `TaskClient` forwards this
+     * to `renderSlimIndex()` so consumers can tighten the model-visible
+     * block below the 8000-char default. `undefined` means "renderer
+     * picks the default".
+     */
+    get indexCharBudget() {
+        return this.config.indexCharBudget;
+    }
+    /**
+     * Constructor-supplied `!command` preprocessing config.
+     * `undefined` means "default disabled" — the MCP server's `get_skill`
+     * handler short-circuits when this is `undefined` or `mode: 'disabled'`.
+     */
+    get preprocessingConfig() {
+        return this.config.preprocessing;
+    }
+    /**
+     * Constructor-supplied embedder, if any. `undefined` means
+     * "no pre-filter; rely on render-side truncation".
+     */
+    get embedder() {
+        return this.config.embedder;
+    }
+    /**
+     * Constructor-supplied embedding-pre-filter tuning. `undefined` means
+     * "use documented defaults" (`topK: 8`, `minScore: 0.35`).
+     */
+    get activationConfig() {
+        return this.config.activation;
+    }
+    /**
+     * List every catalog entry. Awaits discovery on first call. Returns
+     * latest-version-only by default; pass `{ includeAllVersions: true }`
+     * to surface every version recorded during discovery.
+     */
+    async list(opts = {}) {
+        const snapshot = await this.discover();
+        if (opts.includeAllVersions === true)
+            return snapshot.skills;
+        return collectLatestVersions(snapshot.skills);
+    }
+    /**
+     * Resolve a skill specifier (`name`, `vendor/name`, or `vendor/name@version`)
+     * to a `ParsedSkill` or `null` if no match.
+     *
+     * - Bare name: returns the latest-version match of any vendor; if multiple
+     *   vendors ship a skill of that name, the highest-precedence source wins.
+     * - `vendor/name`: latest version of that vendor's skill.
+     * - `vendor/name@version`: exact pin.
+     */
+    async get(specifier) {
+        const snapshot = await this.discover();
+        return resolveSpecifier(snapshot.skills, specifier);
+    }
+    /**
+     * Verify every name in `specifiers` resolves. Throws on the first
+     * unresolved entry — the SDK uses this from the wire boundary to fail
+     * loud on caller-pinned activation per `skills-activation.md` §2.
+     */
+    async resolveOrThrow(specifiers) {
+        const snapshot = await this.discover();
+        const out = [];
+        for (const spec of specifiers) {
+            const resolved = resolveSpecifier(snapshot.skills, spec);
+            if (resolved === null) {
+                throw new SkillNotFoundError(spec);
+            }
+            out.push(resolved);
+        }
+        return out;
+    }
+    // ---------------------------------------------------------------------
+    // Trust + requires caps + active-skill state
+    // ---------------------------------------------------------------------
+    /**
+     * Whether `skill` is trusted enough to honor its declarative affordances
+     * (`allowed-tools`, `disable-model-invocation: false`, `hooks`). True for
+     * the `'trusted'` / `'operator'` tiers; for `'third-party'` true iff the
+     * skill's source identity is in `trustedSources`.
+     */
+    isTrusted(skill) {
+        return isSkillTrusted(skill, this.trustedSourceIdentities);
+    }
+    /**
+     * Resolved `requires:` caps with defaults filled in. Read by the
+     * activation pipeline (`TaskClient` caller-pin + `QodoSkillsMcpServer.get_skill`).
+     */
+    get requiresCapsResolved() {
+        return this.requiresCaps;
+    }
+    /**
+     * Snapshot of currently active skill FQNs. The active set is union of
+     * (a) caller-pinned skills the SDK injected for the latest dispatch and
+     * (b) skills the model loaded via `qodo-skills.get_skill`. Returned
+     * sorted for stable test output.
+     */
+    getActiveSkills() {
+        return [...this.activeFqns].sort();
+    }
+    /**
+     * Mark a skill FQN as active. Idempotent — re-marking emits no extra
+     * event. Returns `true` iff the FQN was newly added (i.e., this is a
+     * fresh activation, not a cache hit).
+     *
+     * The caller is responsible for emitting `sdk.skill.activated` — the
+     * event carries `source: 'caller' | 'llm'` which only the caller knows.
+     * `markActive` just owns the set membership.
+     */
+    markActive(fqn) {
+        if (this.activeFqns.has(fqn))
+            return false;
+        this.activeFqns.add(fqn);
+        return true;
+    }
+    /**
+     * Remove a skill FQN from the active set. Returns `true` iff it was
+     * present. Used by `QodoSkillsMcpServer.dispose` and (rarely) by
+     * consumers programmatically rolling back activation.
+     */
+    deactivate(fqn) {
+        return this.activeFqns.delete(fqn);
+    }
+    /**
+     * Clear the active set entirely. Called by `QodoSkillsMcpServer.dispose`
+     * on `disconnect()` so the next `connect()` starts cold.
+     */
+    resetActive() {
+        this.activeFqns.clear();
+    }
+    /**
+     * @internal — used by `QodoSkillsMcpServer` to share the active set with
+     * the body cache. Exposes the same `Set` the manager uses; mutations
+     * propagate to both surfaces.
+     */
+    get internalActiveFqns() {
+        return this.activeFqns;
+    }
+    // ---------------------------------------------------------------------
+    // Hot reload watcher (dev mode)
+    // ---------------------------------------------------------------------
+    /**
+     * Begin watching every configured local source directory for SKILL.md
+     * changes. Idempotent — calling twice has no extra effect.
+     *
+     * Requires `discover()` to have completed; the watcher targets only
+     * directories already known to be on disk. New top-level source dirs
+     * appearing post-startup are NOT auto-watched (operators would
+     * typically `stopWatching()` + reconfigure + start a new client).
+     *
+     * `package` and `bundled` sources are intentionally NOT watched —
+     * those ship with the application code and shouldn't churn at
+     * runtime. Watching them would expose tampering surface without
+     * meaningful upside.
+     *
+     * Default behavior is determined by `SkillsConfig.watch`:
+     * `undefined`/`false` ⇒ no-op; `true` ⇒ start watching after the first
+     * `discover()` resolves.
+     */
+    async startWatching() {
+        // Overlapping `startWatching()` calls (e.g. auto-start + an
+        // explicit manual start) could race past the
+        // `watchers.size > 0` early-out and install duplicate `FSWatcher`s
+        // for the same directory. Serialise through an in-flight promise so
+        // every concurrent caller waits on the same install pass.
+        if (this.startWatchingPromise !== null) {
+            await this.startWatchingPromise;
+            return;
+        }
+        this.startWatchingPromise = this.doStartWatching().finally(() => {
+            this.startWatchingPromise = null;
+        });
+        await this.startWatchingPromise;
+    }
+    async doStartWatching() {
+        await this.discover();
+        if (this.watchers.size > 0)
+            return;
+        const seen = new Set();
+        for (const result of this.snapshot.bySource) {
+            // Skip source types that ship with code and shouldn't churn.
+            if (!isWatchableSourceType(result.source.type))
+                continue;
+            // Watch each discovered skill's parent (the `<source>/<skill-dir>`'s
+            // parent — typically the source root). That covers add/change/delete
+            // of the skill's own SKILL.md and sibling adds (a new skill dir
+            // appearing alongside an existing one).
+            for (const walked of result.skills) {
+                const parent = path.dirname(walked.dirPath);
+                if (seen.has(parent))
+                    continue;
+                const real = await safeRealPath(parent);
+                if (real === null || seen.has(real))
+                    continue;
+                seen.add(real);
+                this.installWatcher(real);
+            }
+            // Also watch the source's declared root if it has one (covers an
+            // empty source — no skills yet, but operators expect adds to be
+            // picked up). When `source.path` is omitted (the common default
+            // for `project` / `user`), the watcher needs to know the
+            // resolved default location too; `resolveDefaultWatchRoot`
+            // bridges the env-based defaulting the walker itself does.
+            const root = watchableRoot(result.source) ?? resolveDefaultWatchRoot(result.source, this.env);
+            if (root !== null) {
+                const real = await safeRealPath(root);
+                if (real !== null && !seen.has(real)) {
+                    seen.add(real);
+                    this.installWatcher(real);
+                }
+            }
+        }
+    }
+    /**
+     * Tear down every active watcher and cancel any pending debounce
+     * timer. Safe to call multiple times. Called automatically by
+     * `dispose()`.
+     */
+    stopWatching() {
+        for (const watcher of this.watchers.values()) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // Closing a watcher can throw on some platforms when the
+                // underlying directory is already gone; ignored — there's
+                // nothing to recover.
+            }
+        }
+        this.watchers.clear();
+        if (this.rebuildTimer !== null) {
+            clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = null;
+        }
+    }
+    /**
+     * Tear down the manager — equivalent to `stopWatching()`. Provided as
+     * a parallel to `QodoSkillsMcpServer.dispose()` so consumer code can
+     * call both in a uniform shutdown sequence.
+     */
+    dispose() {
+        this.stopWatching();
+        this.rebuildListeners.clear();
+    }
+    /** Current catalog epoch counter. `0` before the first `discover()`. */
+    get catalogEpoch() {
+        return this.epoch;
+    }
+    /**
+     * Subscribe to rebuild events. The listener fires after every
+     * successful watcher-triggered rebuild (NOT on the initial discover).
+     * Returns an unsubscribe function. Used primarily by tests.
+     */
+    onRebuild(listener) {
+        this.rebuildListeners.add(listener);
+        return () => {
+            this.rebuildListeners.delete(listener);
+        };
+    }
+    /**
+     * Trigger an out-of-band rebuild. Test seam — production code goes
+     * through the debounced watcher path. The rebuild is in-flight
+     * already if another rebuild is queued; returns the same in-flight
+     * promise to avoid double-rebuild races.
+     */
+    rebuildNow() {
+        if (this.rebuildPromise !== null) {
+            // A change that arrives mid-rebuild must not be silently dropped.
+            // Record the trailing request; the current rebuild's finally-hook
+            // will fire another pass.
+            this.pendingRebuild = true;
+            return this.rebuildPromise;
+        }
+        this.rebuildPromise = this.doRebuild('watcher_event').finally(() => {
+            this.rebuildPromise = null;
+            if (this.pendingRebuild) {
+                this.pendingRebuild = false;
+                // Schedule the follow-up through the debouncer so multiple
+                // late changes coalesce into one extra rebuild.
+                this.scheduleRebuild();
+            }
+        });
+        return this.rebuildPromise;
+    }
+    installWatcher(dir) {
+        if (this.watchers.has(dir))
+            return;
+        let watcher;
+        try {
+            watcher = fsWatch(dir, { recursive: true });
+        }
+        catch (err) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                path: dir,
+                severity: 'warning',
+                message: `watch failed for ${dir}: ${errorMessage(err)}`,
+            });
+            return;
+        }
+        watcher.on('change', () => this.scheduleRebuild());
+        watcher.on('error', (err) => {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                path: dir,
+                severity: 'warning',
+                message: `watcher error for ${dir}: ${err.message}`,
+            });
+        });
+        this.watchers.set(dir, watcher);
+    }
+    scheduleRebuild() {
+        if (this.rebuildTimer !== null)
+            return;
+        // If a rebuild is already in flight, record the trailing request
+        // and let the in-flight rebuild's finally-hook re-fire — no need
+        // to start a separate debounce timer that would race the hook.
+        if (this.rebuildPromise !== null) {
+            this.pendingRebuild = true;
+            return;
+        }
+        this.rebuildTimer = setTimeout(() => {
+            this.rebuildTimer = null;
+            this.rebuildNow().catch(() => {
+                // Errors are emitted as `sdk.skill.error` inside `doRebuild`;
+                // there's no caller to propagate to from the watcher path.
+            });
+        }, 100);
+    }
+    async doRebuild(reason) {
+        const previous = this.snapshot;
+        const next = await this.buildCatalog();
+        this.epoch += 1;
+        const stamped = { ...next, epoch: this.epoch };
+        this.snapshot = stamped;
+        this.emitEvent({
+            kind: 'sdk.skill.catalog_epoch_bumped',
+            from: this.epoch - 1,
+            to: this.epoch,
+            reason,
+        });
+        if (previous !== null) {
+            this.diffAndEmit(previous, stamped);
+            // `onRebuild()` is documented as firing only on watcher-triggered
+            // rebuilds, not on the initial discover.
+            // Listeners registered before `discover()` would otherwise see
+            // an unexpected callback at startup. Gate on `previous !== null`
+            // so the initial-discover path stays silent.
+            for (const listener of this.rebuildListeners) {
+                try {
+                    listener(stamped);
+                }
+                catch {
+                    // Listener sinks must not break the rebuild loop.
+                }
+            }
+        }
+        return stamped;
+    }
+    diffAndEmit(prev, next) {
+        const prevByFqn = new Map();
+        for (const s of prev.skills)
+            prevByFqn.set(s.fqn, s);
+        const nextByFqn = new Map();
+        for (const s of next.skills)
+            nextByFqn.set(s.fqn, s);
+        for (const [fqn, before] of prevByFqn) {
+            if (!nextByFqn.has(fqn)) {
+                this.emitEvent({
+                    kind: 'sdk.skill.removed',
+                    fqn,
+                    source: before.source,
+                });
+            }
+        }
+        // `sdk.skill.discovered` events for fresh adds are emitted from
+        // inside `doDiscover()` already; nothing more to do here for the
+        // add path.
+    }
+    // ---------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------
+    /**
+     * Walk every configured source + parse + validate + assemble the
+     * catalog. Pure with respect to `this.snapshot` — the caller decides
+     * how to publish the returned snapshot (initial discover stamps the
+     * epoch; rebuild diffs against the prior snapshot first).
+     */
+    async buildCatalog() {
+        const sources = this.resolveSourcesList();
+        const bySource = [];
+        const allCandidates = [];
+        for (const source of sources) {
+            const start = Date.now();
+            let result;
+            try {
+                result = await walkSource(source, this.env);
+            }
+            catch (err) {
+                result = {
+                    source,
+                    skills: [],
+                    errors: [{ message: `walker threw: ${errorMessage(err)}` }],
+                };
+            }
+            const durationMs = Date.now() - start;
+            this.emitEvent({
+                kind: 'sdk.skill.source_scanned',
+                source: result.source,
+                durationMs,
+                count: result.skills.length,
+                errors: result.errors.length,
+            });
+            for (const errEntry of result.errors) {
+                this.emitEvent({
+                    kind: 'sdk.skill.error',
+                    source: result.source,
+                    ...(errEntry.path !== undefined ? { path: errEntry.path } : {}),
+                    severity: 'error',
+                    message: errEntry.message,
+                });
+            }
+            bySource.push(result);
+            for (const walked of result.skills) {
+                allCandidates.push({
+                    walked,
+                    source: result.source,
+                    ...(result.resolvedVendor !== undefined ? { resolvedVendor: result.resolvedVendor } : {}),
+                });
+            }
+        }
+        // Parse + validate each candidate. Keyed by FQN; later candidates of
+        // the same FQN are shadow-resolved (highest-precedence source wins).
+        const byFqn = new Map();
+        const excluded = [];
+        const seenWithinSource = new Set();
+        let currentSourceKey = '';
+        for (const candidate of allCandidates) {
+            const sourceKey = sourceIdentity(candidate.source);
+            if (sourceKey !== currentSourceKey) {
+                seenWithinSource.clear();
+                currentSourceKey = sourceKey;
+            }
+            const parsed = await this.parseAndValidate(candidate.walked, candidate.source, candidate.resolvedVendor);
+            if (parsed === null)
+                continue;
+            const fqn = parsed.fqn;
+            const intraSourceKey = `${sourceKey}|${fqn}`;
+            if (seenWithinSource.has(intraSourceKey)) {
+                this.emitEvent({
+                    kind: 'sdk.skill.error',
+                    source: candidate.source,
+                    path: candidate.walked.skillFilePath,
+                    severity: 'error',
+                    message: `duplicate FQN within source: ${fqn}`,
+                });
+                excluded.push({
+                    source: candidate.source,
+                    path: candidate.walked.skillFilePath,
+                    reason: `duplicate FQN within source: ${fqn}`,
+                });
+                // Also drop any prior winner from the catalog if it came from
+                // the same source — both copies excluded.
+                const prior = byFqn.get(fqn);
+                if (prior !== undefined && sourceIdentity(prior.source) === sourceKey) {
+                    byFqn.delete(fqn);
+                }
+                continue;
+            }
+            seenWithinSource.add(intraSourceKey);
+            const existing = byFqn.get(fqn);
+            if (existing === undefined) {
+                byFqn.set(fqn, parsed);
+                this.emitEvent({
+                    kind: 'sdk.skill.discovered',
+                    fqn,
+                    source: parsed.source,
+                    version: parsed.version,
+                    trustTier: parsed.trustTier,
+                });
+                // Emit the dedicated tier-assigned event for audit-log replay.
+                // The information is already encoded in
+                // `sdk.skill.discovered.trustTier`; the explicit event surface
+                // lets operators wire a security-only sink without inheriting
+                // the rest of the discovery telemetry volume.
+                this.emitEvent({
+                    kind: 'sdk.skill.tier_assigned',
+                    skill: parsed.fqn,
+                    tier: parsed.trustTier,
+                });
+                continue;
+            }
+            // Same FQN seen earlier; the earlier source has higher precedence
+            // (we iterate `sources` in highest-first order). The new one is
+            // shadowed.
+            this.emitEvent({
+                kind: 'sdk.skill.shadowed',
+                fqn,
+                winner: { source: existing.source, version: existing.version },
+                loser: { source: parsed.source, version: parsed.version },
+            });
+            excluded.push({
+                source: parsed.source,
+                path: parsed.skillFile,
+                reason: `shadowed by ${sourceIdentity(existing.source)}/${existing.version}`,
+            });
+        }
+        const skills = [...byFqn.values()].sort((a, b) => a.fqn.localeCompare(b.fqn));
+        // Validate any configured lockfile *after* discovery. Skills not in
+        // the lockfile are still included; pinned entries that drift or are
+        // unreachable fail boot loudly.
+        await this.applyLockfile(skills);
+        // `epoch` is stamped by the caller (`doRebuild`); placeholder `0`
+        // here keeps the shape consistent without redundant copying.
+        const snapshot = {
+            skills,
+            bySource,
+            excluded,
+            epoch: 0,
+        };
+        return snapshot;
+    }
+    /**
+     * Locate + apply the lockfile per `SkillsConfig.lockfile`. When
+     * `'off'`, returns immediately. When `'discover'`, searches the
+     * configured CWD; when an explicit `{ path }`, loads it directly.
+     *
+     * Validation outcomes:
+     *
+     *   - All entries match → return silently.
+     *   - At least one drifts → emit `sdk.skill.lock_drift` per offender + throw.
+     *   - At least one unreachable → emit `sdk.skill.lock_unreachable` + throw.
+     *
+     * Throws `LockfileValidationError` so the wire boundary fails loud
+     * rather than serving a divergent catalog.
+     */
+    async applyLockfile(skills) {
+        const policy = this.config.lockfile ?? 'discover';
+        if (policy === 'off')
+            return;
+        let lockfilePath = null;
+        if (typeof policy === 'object' && policy !== null) {
+            lockfilePath = policy.path;
+        }
+        else {
+            // Discover the lockfile from the configured CWD AND from the
+            // nearest ancestor directory containing `agent.toml` — matches the
+            // documented "beside agent.toml" behavior.
+            // Walk up at most 8 levels so the search is bounded even when the
+            // CWD is buried in a deep monorepo.
+            const searchPaths = await collectLockfileSearchPaths(this.env.cwd);
+            lockfilePath = await findLockfile(searchPaths);
+        }
+        if (lockfilePath === null)
+            return;
+        let lockfile;
+        try {
+            lockfile = await loadLockfile(lockfilePath);
+        }
+        catch (err) {
+            // Malformed lockfile is a configuration error, surfaced through the
+            // emit sink and rethrown so the consumer fails fast.
+            const message = err instanceof Error ? err.message : String(err);
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                severity: 'error',
+                message: `failed to parse lockfile at ${lockfilePath}: ${message}`,
+            });
+            throw err;
+        }
+        const byFqn = new Map();
+        for (const skill of skills)
+            byFqn.set(skill.fqn, skill);
+        const failures = [];
+        for (const entry of lockfile.skills) {
+            const discovered = byFqn.get(entry.fqn);
+            const outcome = await validateLockfileEntry(entry, discovered);
+            switch (outcome.outcome) {
+                case 'ok':
+                    continue;
+                case 'drift': {
+                    this.emitEvent({
+                        kind: 'sdk.skill.lock_drift',
+                        fqn: entry.fqn,
+                        expectedSha256: outcome.expectedSha256,
+                        actualSha256: outcome.actualSha256,
+                    });
+                    failures.push({
+                        fqn: entry.fqn,
+                        kind: 'drift',
+                        message: `expected sha256 ${outcome.expectedSha256}, got ${outcome.actualSha256}`,
+                    });
+                    break;
+                }
+                case 'unreachable': {
+                    this.emitEvent({
+                        kind: 'sdk.skill.lock_unreachable',
+                        fqn: entry.fqn,
+                        source: entry.source,
+                    });
+                    failures.push({
+                        fqn: entry.fqn,
+                        kind: 'unreachable',
+                        message: outcome.reason,
+                    });
+                    break;
+                }
+            }
+        }
+        if (failures.length > 0) {
+            const summary = failures
+                .map((f) => `  - ${f.fqn}: ${f.kind} (${f.message})`)
+                .join('\n');
+            throw new LockfileValidationError(failures[0].fqn, failures[0].kind, `lockfile validation failed for ${failures.length} skill(s):\n${summary}\n` +
+                'Resolve drift via `qodo skills lock --update <fqn>`.');
+        }
+    }
+    resolveSourcesList() {
+        if (this.config.sources !== undefined)
+            return this.config.sources;
+        // Default: project + user + bundled. We deliberately leave package
+        // / config / cli-fetched off the default because they require
+        // explicit opt-in (config has no default path; package needs a
+        // packageName; cli-fetched needs the CLI command to have run).
+        return DEFAULT_SOURCE_ORDER.flatMap((type) => {
+            switch (type) {
+                case 'project':
+                    return [{ type: 'project' }];
+                case 'user':
+                    return [{ type: 'user' }];
+                case 'bundled':
+                    return [{ type: 'bundled' }];
+                default:
+                    return [];
+            }
+        });
+    }
+    async parseAndValidate(walked, source, resolvedVendor) {
+        const dirName = path.basename(walked.dirPath);
+        // F2: enforce the file-size hard cap *before* `fs.readFile` so an
+        // attacker-controlled multi-megabyte SKILL.md cannot exhaust memory
+        // through the walker / parser path.
+        //
+        // We re-stat here at the read boundary rather than trusting
+        // `walked.size` (captured during discovery) — between scan and
+        // read the file can grow, which would otherwise bypass the cap.
+        // The walker's `size` is kept for early-exit on already-huge
+        // files; this re-stat closes the TOCTTOU window.
+        let liveStat;
+        try {
+            liveStat = await fs.stat(walked.skillFilePath);
+        }
+        catch (err) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: 'error',
+                message: `stat failed: ${errorMessage(err)}`,
+            });
+            return null;
+        }
+        if (liveStat.size > SKILL_FILE_HARD_BYTES) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: 'error',
+                message: `SKILL.md exceeds the ${SKILL_FILE_HARD_BYTES}-byte file cap ` +
+                    `(${liveStat.size} bytes); skipping without reading`,
+            });
+            return null;
+        }
+        let text;
+        try {
+            text = await fs.readFile(walked.skillFilePath, 'utf-8');
+        }
+        catch (err) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: 'error',
+                message: `readFile failed: ${errorMessage(err)}`,
+            });
+            return null;
+        }
+        // Defensive last-resort: even with the pre-read stat, a race between
+        // `stat` and `readFile` can grow the file by an unbounded amount.
+        // Verify the actual loaded byte length and reject if it exceeded
+        // the cap during the read window.
+        const actualBytes = Buffer.byteLength(text, 'utf-8');
+        if (actualBytes > SKILL_FILE_HARD_BYTES) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: 'error',
+                message: `SKILL.md grew past the ${SKILL_FILE_HARD_BYTES}-byte file cap ` +
+                    `during read (${actualBytes} bytes); skipping`,
+            });
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = parseSkillDocument(text);
+        }
+        catch (err) {
+            const msg = err instanceof SkillParseError ? err.message : errorMessage(err);
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: 'error',
+                message: msg,
+            });
+            return null;
+        }
+        const validated = validateFrontmatter(parsed.frontmatter, dirName);
+        for (const issue of validated.issues) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: issue.severity,
+                message: issue.field !== undefined ? `${issue.field}: ${issue.message}` : issue.message,
+            });
+        }
+        for (const unknownField of validated.unknownFields) {
+            this.emitEvent({
+                kind: 'sdk.skill.unknown_field',
+                path: walked.skillFilePath,
+                field: unknownField,
+            });
+        }
+        // Fatal frontmatter issues exclude the skill.
+        if (validated.issues.some((i) => i.severity === 'error')) {
+            return null;
+        }
+        const bodyValidation = validateBody(parsed.body);
+        for (const issue of bodyValidation.issues) {
+            this.emitEvent({
+                kind: 'sdk.skill.error',
+                source,
+                path: walked.skillFilePath,
+                severity: issue.severity,
+                message: issue.message,
+            });
+        }
+        if (bodyValidation.issues.some((i) => i.severity === 'error')) {
+            return null;
+        }
+        const vendor = resolveVendor(validated.frontmatter.vendor, source, resolvedVendor);
+        const version = validated.frontmatter.version ?? DEFAULT_VERSION;
+        const name = validated.frontmatter.name; // validator guarantees presence
+        const fqn = `${vendor}/${name}@${version}`;
+        const fqnNoVersion = `${vendor}/${name}`;
+        // `min_sdk_version` enforcement: exclude with a warning if the running
+        // SDK is older than the declared minimum.
+        if (validated.frontmatter.min_sdk_version !== undefined && this.config.sdkVersion !== undefined) {
+            try {
+                if (semverLessThan(this.config.sdkVersion, validated.frontmatter.min_sdk_version)) {
+                    this.emitEvent({
+                        kind: 'sdk.skill.error',
+                        source,
+                        path: walked.skillFilePath,
+                        severity: 'warning',
+                        message: `min_sdk_version ${validated.frontmatter.min_sdk_version} not met by SDK ${this.config.sdkVersion}`,
+                    });
+                    return null;
+                }
+            }
+            catch {
+                // already reported as a validator error
+            }
+        }
+        const trustTier = SOURCE_TRUST_TIERS[source.type];
+        // Walk supporting-file references in the body. Emits a
+        // warning for each reference deeper than one segment (authors are
+        // encouraged to keep referenced files at the skill root for
+        // discoverability) and a warning for each reference whose target file
+        // doesn't exist. The skill itself still loads — these are advisory
+        // findings the operator can ignore or wire to CI.
+        await this.auditBodyReferences(walked, source, parsed.body);
+        return {
+            fqn,
+            fqnNoVersion,
+            name,
+            vendor,
+            version,
+            path: walked.dirPath,
+            skillFile: walked.skillFilePath,
+            mtimeMs: walked.mtimeMs,
+            frontmatter: validated.frontmatter,
+            body: parsed.body,
+            source,
+            trustTier,
+            raw: parsed.frontmatter,
+        };
+    }
+    /**
+     * Inspect the skill body for `[label](path)` and `get_skill_file("path")`
+     * references; emit:
+     *
+     *   - `sdk.skill.error severity: 'warning'` when the referenced file
+     *     doesn't exist under the skill directory.
+     *   - `sdk.skill.error severity: 'warning'` when a reference has depth
+     *     greater than 1 (e.g. `scripts/helpers/foo.py`). Authors who
+     *     intentionally nest files can ignore this warning.
+     *
+     * The check is best-effort: any `fs.stat` failure other than ENOENT is
+     * silently ignored so a transient filesystem error doesn't poison
+     * discovery.
+     */
+    async auditBodyReferences(walked, source, body) {
+        const refs = extractBodyReferences(body);
+        for (const ref of refs) {
+            if (ref.depth > 1) {
+                this.emitEvent({
+                    kind: 'sdk.skill.error',
+                    source,
+                    path: walked.skillFilePath,
+                    severity: 'warning',
+                    message: `reference '${ref.path}' is ${ref.depth} segments deep — ` +
+                        'authors are encouraged to keep referenced files at the skill root for discoverability',
+                });
+            }
+            // Reject obvious traversal in the reference itself before we touch
+            // the filesystem; the body might be hostile.
+            if (ref.path.split('/').some((seg) => seg === '..')) {
+                this.emitEvent({
+                    kind: 'sdk.skill.error',
+                    source,
+                    path: walked.skillFilePath,
+                    severity: 'warning',
+                    message: `reference '${ref.path}' contains '..' — skipping existence check`,
+                });
+                continue;
+            }
+            const absolute = path.join(walked.dirPath, ref.path);
+            try {
+                await fs.stat(absolute);
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === 'ENOENT') {
+                    this.emitEvent({
+                        kind: 'sdk.skill.error',
+                        source,
+                        path: walked.skillFilePath,
+                        severity: 'warning',
+                        message: `broken reference '${ref.path}' — file not found in skill directory`,
+                    });
+                }
+                // For non-ENOENT errors (permission denied, IO failure), stay
+                // silent — discovery shouldn't gate on transient FS issues.
+            }
+        }
+    }
+    emitEvent(event) {
+        if (this.emit === undefined)
+            return;
+        try {
+            this.emit(scrubEvent(event));
+        }
+        catch {
+            // Telemetry sinks must not break catalog construction; swallow.
+        }
+    }
+}
+/**
+ * Thrown by `SkillsManager.resolveOrThrow` when a caller-pinned specifier
+ * doesn't match anything in the catalog. The wire boundary (TaskClient
+ * startWithAgent / startWithGraph) re-throws these so consumers see a
+ * loud failure per `skills-activation.md` §2.
+ */
+export class SkillNotFoundError extends Error {
+    specifier;
+    constructor(specifier) {
+        super(`Skill not found: ${specifier}`);
+        this.name = 'SkillNotFoundError';
+        this.specifier = specifier;
+    }
+}
+/**
+ * Thrown when a bare-name caller pin matches multiple skills under
+ * different vendors (`acme/code-review` and `local/code-review` both
+ * shipping `name: code-review`). The first-match-wins behavior silently
+ * picked one, which could change at runtime depending on source order.
+ * Force the caller to disambiguate with a `vendor/name` pin.
+ */
+export class SkillAmbiguousPinError extends Error {
+    specifier;
+    candidates;
+    constructor(specifier, candidates) {
+        super(`Skill pin "${specifier}" is ambiguous — multiple vendors ship a skill ` +
+            `of that name: ${candidates.join(', ')}. Pin with a full ` +
+            '`vendor/name` specifier to disambiguate.');
+        this.name = 'SkillAmbiguousPinError';
+        this.specifier = specifier;
+        this.candidates = candidates;
+    }
+}
+/**
+ * Thrown when caller-pinned skills cannot fit inside the slim-index
+ * hard cap (`2 × charBudget`, floored at `charBudget + 4096`). Pinning
+ * is a "must include" contract — silently dropping pins would make the
+ * model behave as if the caller never pinned them; throwing forces the
+ * caller to fix the pin list or raise the budget.
+ */
+export class SkillsBudgetExceededError extends Error {
+    omittedSkills;
+    hardCap;
+    constructor(omittedSkills, hardCap) {
+        super(`caller-pinned skills exceeded the slim-index hard cap (${hardCap} chars). ` +
+            `Omitted: ${omittedSkills.join(', ')}. Reduce the pin list or raise ` +
+            '`SkillsConfig.indexCharBudget`.');
+        this.name = 'SkillsBudgetExceededError';
+        this.omittedSkills = omittedSkills;
+        this.hardCap = hardCap;
+    }
+}
+/**
+ * Thrown when caller-pinned activation can't proceed because of a
+ * `requires:` chain failure — trust violation, depth/breadth/token cap
+ * breach, cycle, or unresolved dependency. The `kind` discriminator
+ * carries the specific reason. Caller-pin
+ * activation is an authoritative contract; failure must be loud rather
+ * than silently dropping the affected skill.
+ */
+export class QodoSkillError extends Error {
+    skill;
+    reason;
+    constructor(skill, reason, message) {
+        super(message);
+        this.name = 'QodoSkillError';
+        this.skill = skill;
+        this.reason = reason;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve `vendor`: explicit frontmatter `vendor:` wins; otherwise the
+ * source-derived default.
+ */
+function resolveVendor(explicit, source, resolvedVendor) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    if (resolvedVendor !== undefined && resolvedVendor.length > 0)
+        return resolvedVendor;
+    const def = SOURCE_DEFAULT_VENDORS[source.type];
+    if (def === '__from_package_name__' && source.type === 'package') {
+        return source.packageName;
+    }
+    if (def === '__from_ref__' && source.type === 'cli-fetched') {
+        const ref = source.ref;
+        if (typeof ref === 'string' && ref.length > 0) {
+            const first = ref.split('/')[0];
+            if (first !== undefined && first.length > 0)
+                return first;
+        }
+        return 'cli-fetched';
+    }
+    return def;
+}
+function sourceIdentity(source) {
+    switch (source.type) {
+        case 'project':
+            return source.path !== undefined ? `project:${source.path}` : 'project';
+        case 'config':
+            return `config:${source.path}`;
+        case 'user':
+            return source.path !== undefined ? `user:${source.path}` : 'user';
+        case 'package':
+            return `package:${source.packageName}`;
+        case 'cli-fetched':
+            return source.ref !== undefined ? `cli-fetched:${source.ref}` : 'cli-fetched';
+        case 'bundled':
+            return source.path !== undefined ? `bundled:${source.path}` : 'bundled';
+    }
+}
+function collectLatestVersions(skills) {
+    const byFqnNoVersion = new Map();
+    for (const skill of skills) {
+        const existing = byFqnNoVersion.get(skill.fqnNoVersion);
+        if (existing === undefined) {
+            byFqnNoVersion.set(skill.fqnNoVersion, skill);
+            continue;
+        }
+        try {
+            if (semverLessThan(existing.version, skill.version)) {
+                byFqnNoVersion.set(skill.fqnNoVersion, skill);
+            }
+        }
+        catch {
+            // both versions semver-invalid (shouldn't happen — validator
+            // catches non-semver) — fall back to FQN string compare
+            if (existing.fqn < skill.fqn)
+                byFqnNoVersion.set(skill.fqnNoVersion, skill);
+        }
+    }
+    return [...byFqnNoVersion.values()].sort((a, b) => a.fqn.localeCompare(b.fqn));
+}
+function resolveSpecifier(skills, specifier) {
+    const versionMatch = /^(.+?)@([^@]+)$/.exec(specifier);
+    if (versionMatch !== null) {
+        const fqnNoVersion = versionMatch[1];
+        const version = versionMatch[2];
+        return skills.find((s) => s.fqnNoVersion === fqnNoVersion && s.version === version) ?? null;
+    }
+    // Bare name or vendor/name.
+    if (specifier.includes('/')) {
+        return collectLatestVersions(skills.filter((s) => s.fqnNoVersion === specifier))[0] ?? null;
+    }
+    // Bare name — find latest of each vendor matching `name === specifier`.
+    const matches = skills.filter((s) => s.name === specifier);
+    if (matches.length === 0)
+        return null;
+    const latest = collectLatestVersions(matches);
+    // If multiple vendors match, take the FIRST in the catalog's source-order.
+    // The catalog itself is sorted by FQN; for bare-name resolution we want
+    // the highest-precedence source's pick, which the catalog construction
+    // already chose (first-wins via the shadowing loop). Pick by smallest
+    // source-precedence index across matches.
+    return latest[0] ?? null;
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/**
+ * F9: scrub absolute filesystem paths out of emitted `SkillEvent`s
+ * before forwarding to the consumer's telemetry sink. Two fields
+ * carry filesystem info:
+ *
+ *   - `event.path` (absolute SKILL.md path) → reduced to the last two
+ *     path segments (`<skill-dir>/<file>`), enough for a developer to
+ *     identify the skill from logs without revealing home directories
+ *     or repo layout.
+ *   - `event.source.path` (for variants that carry it: project / user /
+ *     config / bundled) → stripped. The variant tag alone identifies
+ *     where the skill came from; the absolute resolved path is local
+ *     debug info the manager already retains internally.
+ *
+ * Manager-side state still references absolute paths for symlink
+ * resolution, shadowing, and local debugging. This helper only
+ * sanitises the *emitted* event payload.
+ */
+function scrubEvent(event) {
+    switch (event.kind) {
+        case 'sdk.skill.error':
+            return {
+                ...event,
+                ...(event.source !== undefined ? { source: stripSourcePath(event.source) } : {}),
+                ...(event.path !== undefined ? { path: relativizeSkillPath(event.path) } : {}),
+            };
+        case 'sdk.skill.unknown_field':
+            return { ...event, path: relativizeSkillPath(event.path) };
+        case 'sdk.skill.source_scanned':
+            return { ...event, source: stripSourcePath(event.source) };
+        case 'sdk.skill.discovered':
+            return { ...event, source: stripSourcePath(event.source) };
+        case 'sdk.skill.shadowed':
+            return {
+                ...event,
+                winner: { ...event.winner, source: stripSourcePath(event.winner.source) },
+                loser: { ...event.loser, source: stripSourcePath(event.loser.source) },
+            };
+        // Runtime / activation / trust / substitution / lockfile /
+        // preprocess / fork / removed events. The `skill` / `parent` /
+        // `child` / `fqn` fields are FQNs (no
+        // filesystem leakage); other payload fields carry no path data. The
+        // `lock_unreachable` variant carries a `source`, which gets the same
+        // path stripping the other source-carrying events get.
+        case 'sdk.skill.loaded':
+        case 'sdk.skill.file_loaded':
+        case 'sdk.skill.file_rejected':
+        case 'sdk.skill.invocation_denied':
+        case 'sdk.skill.activated':
+        case 'sdk.skill.disable_model_invocation_overridden':
+        case 'sdk.skill.allowed_tools_applied':
+        case 'sdk.skill.allowed_tools_advisory':
+        case 'sdk.skill.allowed_tools_unmatched':
+        case 'sdk.skill.hooks_ignored':
+        case 'sdk.skill.tier_assigned':
+        case 'sdk.skill.requires_trust_denied':
+        case 'sdk.skill.requires_cap_exceeded':
+        case 'sdk.skill.substitution_warn':
+        case 'sdk.skill.lock_drift':
+        case 'sdk.skill.preprocess_executed':
+        case 'sdk.skill.preprocess_blocked':
+        case 'sdk.skill.fork_declined':
+        case 'sdk.skill.catalog_epoch_bumped':
+        case 'sdk.skill.index_filtered':
+            return event;
+        case 'sdk.skill.lock_unreachable':
+        case 'sdk.skill.removed':
+            return { ...event, source: stripSourcePath(event.source) };
+        default:
+            return event;
+    }
+}
+/**
+ * Identify the top-level directory to watch for hot reload on a given
+ * source variant. Returns `null` for variants whose root we can't
+ * point to without re-walking the env.
+ */
+function watchableRoot(source) {
+    switch (source.type) {
+        case 'project':
+            return source.path ?? null;
+        case 'config':
+            return source.path;
+        case 'user':
+            return source.path ?? null;
+        case 'cli-fetched':
+        case 'package':
+        case 'bundled':
+            return null;
+    }
+}
+/**
+ * Whether a source-type is eligible for hot-reload watching. `package`
+ * + `bundled` ship with code and shouldn't churn at runtime; `cli-fetched`
+ * is intentionally static (the CLI command stamps a frozen ref).
+ */
+function isWatchableSourceType(type) {
+    return type === 'project' || type === 'config' || type === 'user';
+}
+/**
+ * Resolve the env-derived default directory for sources whose `path`
+ * field is optional (`project` / `user`). Mirrors the walker's
+ * defaulting logic so the watcher can target the same directory the
+ * discoverer scanned, even when no skills exist there yet. Returns
+ * `null` for source variants without an env-derived default.
+ *
+ * Defaults `project` to the env CWD and `user` to
+ * `$XDG_CONFIG_HOME/qodo/skills` or `~/.qodo/skills`.
+ */
+function resolveDefaultWatchRoot(source, env) {
+    if (source.type === 'project') {
+        return path.join(env.cwd, '.qodo', 'skills');
+    }
+    if (source.type === 'user') {
+        const xdg = env.env['XDG_CONFIG_HOME'];
+        if (xdg !== undefined && xdg.length > 0)
+            return path.join(xdg, 'qodo', 'skills');
+        return path.join(env.homedir, '.qodo', 'skills');
+    }
+    return null;
+}
+/**
+ * Fill `SkillsConfig.requires` defaults. Invalid (non-finite, non-positive)
+ * inputs fall back to the documented defaults rather than throwing — the
+ * caps are defense-in-depth; a misconfigured cap should not break the
+ * activation path.
+ */
+function resolveRequiresCaps(config) {
+    const maxDepth = pickPositiveInt(config?.maxDepth, REQUIRES_DEFAULT_MAX_DEPTH);
+    const maxTransitive = pickPositiveInt(config?.maxTransitive, REQUIRES_DEFAULT_MAX_TRANSITIVE);
+    const maxTransitiveTokens = pickPositiveInt(config?.maxTransitiveTokens, REQUIRES_DEFAULT_MAX_TRANSITIVE_TOKENS);
+    return { maxDepth, maxTransitive, maxTransitiveTokens };
+}
+function pickPositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function stripSourcePath(source) {
+    switch (source.type) {
+        case 'project':
+        case 'user':
+        case 'bundled':
+            return { type: source.type };
+        case 'config':
+            // `config` requires `path` in the type — replace with the basename
+            // so the operator can still tell `config:foo` apart from
+            // `config:bar` without exposing the absolute resolved location.
+            return { type: 'config', path: path.basename(source.path) };
+        case 'package':
+            return source.path !== undefined
+                ? { type: 'package', packageName: source.packageName, path: path.basename(source.path) }
+                : { type: 'package', packageName: source.packageName };
+        case 'cli-fetched':
+            return source;
+    }
+}
+/**
+ * Reduce an absolute SKILL.md path to its last two segments, e.g.
+ * `/path/to/.qodo/skills/code-review/SKILL.md` → `code-review/SKILL.md`.
+ * Non-absolute paths and very short paths pass through unchanged.
+ */
+function relativizeSkillPath(absPath) {
+    if (!path.isAbsolute(absPath))
+        return absPath;
+    const segments = absPath.split(/[/\\]/).filter((s) => s.length > 0);
+    if (segments.length <= 2)
+        return segments.join('/');
+    return segments.slice(-2).join('/');
+}
+/**
+ * Build the search-path list for lockfile discovery. Returns:
+ *
+ *   1. `cwd` (highest priority).
+ *   2. The nearest ancestor of `cwd` that contains `agent.toml`. Walks
+ *      up at most {@link AGENT_TOML_WALK_DEPTH} levels so the search
+ *      is bounded even in deeply-nested directory trees.
+ *
+ * Both directories are searched in order; the first `qodo.lock.yaml`
+ * hit wins. Used by `applyLockfile()` to satisfy the docs' "alongside
+ * agent.toml" semantics.
+ */
+async function collectLockfileSearchPaths(cwd) {
+    const out = [cwd];
+    let current = cwd;
+    for (let depth = 0; depth < AGENT_TOML_WALK_DEPTH; depth += 1) {
+        const candidate = path.join(current, 'agent.toml');
+        try {
+            const stat = await fs.stat(candidate);
+            if (stat.isFile()) {
+                // agent.toml lives at `current` — the lockfile would sit next
+                // to it. Add `current` to the search list unless it's already
+                // included as the CWD.
+                if (current !== cwd)
+                    out.push(current);
+                return out;
+            }
+        }
+        catch {
+            // Missing agent.toml at this level — keep walking up.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // hit the filesystem root
+        current = parent;
+    }
+    return out;
+}
+/** Maximum levels of parent directories the lockfile search walks. */
+const AGENT_TOML_WALK_DEPTH = 8;
+//# sourceMappingURL=manager.js.map