Merge latest master into codex/migrate-to-oxlint

packages/skill/skill/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/skill/README.md
-README.md: 639616d0b75f960e9ccd48546d44db841372bbe2
-README.zh.md: d2191d54502121c68976ead2541a0588a0530160
+README.md: f538ae668ccff291be86348627d5547150f460df
+README.zh.md: 8a44f684ea4d9519a0af7866d272a8e7834aeda6

packages/skill/skill/README.md

@@ -10,10 +10,15 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 
 ### Public API
 
-- `ctx.skills.registerProvider(provider): () => void` Registers a readonly provider by unique `provider.name`. Duplicate provider names throw, and `runtime` is reserved for `ctx.skills.register(...)`. The registry borrows the provider object and invokes its methods directly. The registration is effect-scoped and HMR-safe, and the exact Cordis disposer supports ordered composite teardown.
-- `ctx.skills.list({ cwd?, signal? })` Borrows the readonly lookup options, then returns model-invocable summaries for the current workspace, merged across providers and sorted by name.
-- `ctx.skills.get(name, { cwd?, signal? })` Uses the same readonly options and winning candidate for discovery and loading, rechecks cancellation after discovery or a cache hit, races provider loading against the signal, validates the loaded definition, then returns it, including disabled-for-model skills.
-- `ctx.skills.register(skill): () => void` Registers a readonly runtime embedded skill, adding `provider: "runtime"` when omitted. Same-name runtime registrations are first-wins: a duplicate logs a warning and gets a no-op disposer. Successful registrations return the exact Cordis disposer for ordered composite teardown.
+- `ctx.skills.registerProvider(create): () => void` Calls a synchronous provider factory with `{ signal, invalidate }`, then registers its readonly result by unique `provider.name`. Duplicate names throw, `runtime` is reserved, and failed registration aborts the signal. The exact Cordis disposer unregisters the provider, aborts the signal, and preserves ordered composite teardown.
+- `ctx.skills.snapshot({ cwd?, signal? })` Returns the invocation-neutral `{ skills, complete }` observation. `complete` is false when any provider rejects or explicitly reports incomplete discovery, or when a second catalog revision races the bounded retry; candidates supplied by that observation remain in this result, which is never cached.
+- `ctx.skills.list({ cwd?, signal? })` Borrows the readonly lookup options, then returns every winning summary for the current workspace, merged across providers and sorted by name. Consumers apply `isModelInvocable(skill)` or `isUserInvocable(skill)` at their own boundary.
+- `ctx.skills.get(name, { cwd?, signal? })` Uses the same readonly options and winning candidate for discovery and loading, rechecks cancellation after discovery or a cache hit, races provider loading against the signal, validates the loaded definition, then returns it regardless of invocation policy.
+- `ctx.skills.register(skill): () => void` Registers a readonly runtime embedded skill, adding the all-invocable policy and `provider: "runtime"` when omitted. Same-name runtime registrations are first-wins: a duplicate logs a warning and gets a no-op disposer. Successful registrations return the exact Cordis disposer for ordered composite teardown.
+
+### Events
+
+- `skills/change` is an unfiltered invalidation notification emitted after a provider or runtime contribution is registered or disposed and after an active provider's registration control invalidates. It carries no catalog or diff: each consumer refetches `snapshot()` with its own lookup options. Listener throws and rejected promises are logged and cannot veto the registry mutation or starve later listeners.
 
 ### Config
 
@@ -21,33 +26,48 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 |---|---|---|
 | `collectCacheMaxEntries` | `128` | Maximum completed cwd/provider catalogs kept in memory. |
 
+### Invocation policy
+
+`SkillSummary.invocation` is a required typed policy object whose positive booleans `modelInvocable` and `userInvocable` describe the two surfaces independently. Providers return this resolved shape on every candidate and definition; only the `SkillRegistration` input may omit it, in which case `register()` supplies `{ modelInvocable: true, userInvocable: true }`. The registry keeps all four combinations so one discovery result can serve model-facing tools, human-facing commands, and trusted internal callers without conflating their catalogs.
+
+| Policy | Model | User |
+|---|---|---|
+| `{ modelInvocable: true, userInvocable: true }` | included | included |
+| `{ modelInvocable: true, userInvocable: false }` | included | excluded |
+| `{ modelInvocable: false, userInvocable: true }` | excluded | included |
+| `{ modelInvocable: false, userInvocable: false }` | excluded | excluded |
+
+`isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains the trusted, policy-neutral loading primitive, so every user- or model-facing consumer must enforce the predicate that matches its surface before exposing or loading a skill.
+
 ## Provider Contract
 
-A provider registers synchronously and performs remote setup, authentication, and discovery in its awaited `list(options)` call. Provider objects, lookup options, candidates, and definitions are borrowed readonly rather than cloned or rebound. Providers should honor `options.signal`; the registry also stops awaiting uncooperative discovery or loading after cancellation.
+A provider factory runs synchronously and receives one registration-scoped control. `control.signal` aborts when registration fails or is disposed; `control.invalidate()` clears completed catalogs only while that exact registration remains active, so late callbacks cannot affect a replacement with the same name. Immutable providers may ignore the control. Remote setup, authentication, and discovery belong in the provider's awaited `list(options)` call. An array return is shorthand for complete discovery; a provider that collected usable candidates but could not establish an authoritative observation returns `{ candidates, complete: false }`. Provider objects, lookup options, candidates, and definitions are borrowed readonly rather than cloned or rebound. Providers should honor `options.signal`; the registry also stops awaiting uncooperative discovery or loading after cancellation.
 
 The registry validates candidates before caching and definitions before returning them. The winning provider receives the same candidate and opaque `locator` it returned from `list()`, allowing backend-specific file, URL, id, or version handles. Callers and providers must preserve the readonly contract.
 
-Contract violations fail fast. A rejected `list()` is treated as a transient source failure: it is logged, skipped, and not cached. Only completed catalogs are cached; a provider or runtime revision change discards an in-flight result and retries. Duplicate names resolve by rank, provider registration order, then provider-local order. Summaries are sorted by skill name.
+Contract violations fail fast. A rejected provider `list()` is treated as a transient source failure and omitted. An explicit incomplete observation still contributes its candidates for `list()` and `get()`, but makes the aggregate snapshot incomplete and uncacheable. A provider or runtime revision change discards an in-flight result and retries once. If the retry is also superseded, its candidates are returned incomplete and uncached so a continuously invalidating provider cannot monopolize the caller. Duplicate names resolve by rank, provider registration order, then provider-local order. Summaries are sorted by skill name.
+
+Definitions remain progressively loaded. `get()` asks the winning provider for the body on every call rather than caching it in this registry. If the returned definition has a different name from the selected candidate, the stale selection is rejected and the registry internally invalidates that exact provider so the next snapshot rediscovers its catalog.
 
 ## Runtime Skills
 
-`ctx.skills.register(...)` is a convenience for embedded runtime skills. Runtime skills use rank `250`: project providers can override them, while they override the shipped local provider's custom and user roots. Runtime definitions and nested resource metadata are borrowed readonly; the service only materializes the top-level definition needed to supply the default `provider`. Registration is first-wins within runtime contributions, so a duplicate contribution cannot remove the active one through its disposer.
+`ctx.skills.register(...)` is a convenience for embedded runtime skills. Runtime skills use rank `250`: project providers can override them, while they override the shipped local provider's custom and user roots. Runtime definitions and nested resource metadata are borrowed readonly; the service materializes one top-level definition to supply omitted invocation and provider defaults. Registration is first-wins within runtime contributions, so a duplicate contribution cannot remove the active one through its disposer.
 
 ## Consumer boundary
 
-The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide the session-prefix catalog and `skill` tool, so providers remain independent of the model surface.
+The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide durable session catalogs and the `skill` tool, so providers remain independent of the model surface.
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-skill`, which renders provider summaries into the session prefix and loaded instructions into retained tool results.
+Indirectly, through `dsh-tool-skill`, which renders provider summaries into durable initial or replacement catalog messages and loaded instructions into retained tool results.
 
 #### KV Cache effect
 
-No direct invalidation; the named consumer owns any request-prefix changes.
+No direct prompt effect. The named consumer owns the durable initial catalog and append-only replacements after invalidation.
 
 ## Known Limitations and Deferred Work
 
-- **Completed catalogs have no TTL or watcher invalidation** — a provider's underlying files or remote data can change without a registration revision, so a cached cwd stays stale until eviction or provider/runtime reload.
+- **Invalidation is provider-driven** — the registry has no TTL and cannot infer that an arbitrary remote source changed; each mutable provider must retain and call its registration-scoped `invalidate()` capability from its own observation mechanism.
 - **Providers are queried sequentially** — one slow cooperative provider delays every provider registered after it; cancellation stops the caller's wait but cannot terminate work an uncooperative provider keeps running.
-- **A provider-list failure removes that whole source for the request** — the registry logs and skips it, with no model-visible diagnostic or partial-catalog recovery contract.
+- **Incomplete observations are not retained** — rejected providers are omitted and explicitly supplied candidates remain available only to the current lookup; the registry owns neither a last-good catalog nor per-provider diagnostics.
 - **Duplicate resolution is first-wins** — later lower-priority candidates are logged and hidden; there is no API to inspect all shadowed definitions.

packages/skill/skill/README.zh.md

@@ -10,10 +10,15 @@
 
 ### 公开 API
 
-- `ctx.skills.registerProvider(provider): () => void` 使用唯一 `provider.name` 注册只读提供方。重复提供方名称会抛错，`runtime` 保留给 `ctx.skills.register(...)`。注册表借用提供方对象，并直接调用其方法。注册作用域绑定到 effect，可安全用于 HMR（热模块替换）；Cordis 返回的原始 disposer 支持有序组合拆卸。
-- `ctx.skills.list({ cwd?, signal? })` 借用只读查找选项，然后返回当前工作区中模型可调用的摘要；这些摘要跨提供方合并，并按名称排序。
-- `ctx.skills.get(name, { cwd?, signal? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后将其返回，包括已对模型禁用的 skill。
-- `ctx.skills.register(skill): () => void` 注册只读运行时嵌入式 skill，省略时添加 `provider: "runtime"`。同名运行时注册使用先到先得：重复项会记录警告，并获得无操作 disposer。成功注册会返回精确的 Cordis disposer，以供有序组合拆卸。
+- `ctx.skills.registerProvider(create): () => void` 调用同步提供方工厂并向其传入 `{ signal, invalidate }`，随后使用唯一 `provider.name` 注册其只读结果。重复提供方名称会抛错，`runtime` 为保留名称；注册失败会中止信号。精确的 Cordis disposer 会注销提供方、中止信号，并保持有序组合拆卸。
+- `ctx.skills.snapshot({ cwd?, signal? })` 返回与调用策略无关的 `{ skills, complete }` 观测。任一提供方调用被拒绝或显式报告发现不完整，或有界重试期间又发生目录修订时，`complete` 为 false；该次观测提供的候选项仍保留在此结果中，但该结果绝不缓存。
+- `ctx.skills.list({ cwd?, signal? })` 借用只读查找选项，然后返回当前工作区中的全部胜出摘要；这些摘要跨提供方合并，并按名称排序。消费方在自身边界调用 `isModelInvocable(skill)` 或 `isUserInvocable(skill)`。
+- `ctx.skills.get(name, { cwd?, signal? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后无论调用策略如何都将其返回。
+- `ctx.skills.register(skill): () => void` 注册只读运行时嵌入式 skill，省略时添加允许模型和用户调用的策略以及 `provider: "runtime"`。同名运行时注册使用先到先得：重复项会记录警告，并获得无操作 disposer。成功注册会返回精确的 Cordis disposer，以供有序组合拆卸。
+
+### 事件
+
+- `skills/change` 是一条不带过滤条件的失效通知，在提供方或运行时贡献注册或释放后，以及活动提供方的注册控制触发失效后发出。它不携带目录或 diff；每个消费方都使用自身的查找选项重新获取 `snapshot()`。监听器抛错或 Promise 拒绝会被记录，既不能否决注册表变更，也不能阻止后续监听器执行。
 
 ### 配置
 
@@ -21,33 +26,48 @@
 |---|---|---|
 | `collectCacheMaxEntries` | `128` | 内存中保留的最大已完成 cwd/提供方目录数。 |
 
+### 调用策略
+
+`SkillSummary.invocation` 是一个必填的类型化策略对象，其正向布尔字段 `modelInvocable` 和 `userInvocable` 分别描述两个接口。提供方会在每个候选项和定义中返回这一已解析形状；只有 `SkillRegistration` 输入可以省略它，此时 `register()` 会补入 `{ modelInvocable: true, userInvocable: true }`。注册表保留全部四种组合，使一次发现结果可以同时服务面向模型的工具、面向用户的命令和受信内部调用方，而不会混淆各自的目录。
+
+| 策略 | 模型 | 用户 |
+|---|---|---|
+| `{ modelInvocable: true, userInvocable: true }` | 包含 | 包含 |
+| `{ modelInvocable: true, userInvocable: false }` | 包含 | 排除 |
+| `{ modelInvocable: false, userInvocable: true }` | 排除 | 包含 |
+| `{ modelInvocable: false, userInvocable: false }` | 排除 | 排除 |
+
+`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
+
 ## 提供方契约
 
-提供方同步注册，并在可等待的 `list(options)` 调用中执行远程设置、身份验证和发现。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
+提供方工厂同步运行，并接收一项注册作用域内的控制能力。注册失败或释放时，`control.signal` 会中止；仅当该精确注册仍处于活动状态时，`control.invalidate()` 才会清除已完成目录，因此延迟回调无法影响同名替代项。不可变提供方可以忽略该控制能力。远程设置、身份验证和发现由提供方可等待的 `list(options)` 调用执行。返回数组是完整发现的简写形式；若提供方已收集到可用候选项，却无法建立权威观测，则返回 `{ candidates, complete: false }`。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
 
 注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读契约。
 
-违反契约时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败：系统记录并跳过该失败，且不缓存结果。只缓存已完成的目录；提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
+违反契约时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
+
+定义仍采用渐进式加载。`get()` 每次调用都会向胜出提供方请求正文，而不是在此注册表中缓存正文。若返回定义的名称不同于所选候选项，系统会拒绝该陈旧选择，并由注册表在内部使该精确提供方失效，以便下一次快照重新发现其目录。
 
 ## 运行时 skill
 
-`ctx.skills.register(...)` 是嵌入式运行时 skill 的便利接口。运行时 skill 使用 rank `250`：项目提供方可覆盖它们，它们则覆盖已发布本地提供方的自定义根目录和用户根目录。运行时定义和嵌套资源元数据均以只读方式借用；服务只物化提供默认 `provider` 所需的顶层定义。运行时贡献内的注册使用先到先得，因此重复贡献无法通过其 disposer 移除当前生效的贡献。
+`ctx.skills.register(...)` 是嵌入式运行时 skill 的便利接口。运行时 skill 使用 rank `250`：项目提供方可覆盖它们，它们则覆盖已发布本地提供方的自定义根目录和用户根目录。运行时定义和嵌套资源元数据均以只读方式借用；服务只物化补入默认调用策略和 `provider` 所需的顶层定义。运行时贡献内的注册使用先到先得，因此重复贡献无法通过其 disposer 移除当前生效的贡献。
 
 ## 消费方边界
 
-注册表不渲染模型指引，也不注册面向模型的工具。[`@deepseek-ai/dsh-tool-skill`](../tool-skill) 消费 `ctx.skills` 以提供会话前缀目录和 `skill` 工具，因此提供方仍与模型接口独立。
+注册表不渲染模型指引，也不注册面向模型的工具。[`@deepseek-ai/dsh-tool-skill`](../tool-skill) 消费 `ctx.skills` 以提供持久会话目录和 `skill` 工具，因此提供方仍与模型接口独立。
 
 ## 模型体验
 
-通过 `dsh-tool-skill` 间接影响模型；该包将提供方摘要渲染到会话前缀中，并将已加载指令渲染到已保留工具结果中。
+通过 `dsh-tool-skill` 间接影响模型；该包将提供方摘要渲染到持久的初始目录或替换目录消息中，并将已加载指令渲染到已保留工具结果中。
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+不直接影响提示词。指定的消费方负责持久初始目录，以及失效后的仅追加式目录替换。
 
 ## 已知限制与暂缓事项
 
-- **已完成的目录没有 TTL 或监听失效机制**：提供方的底层文件或远程数据可在注册修订不变的情况下更改，因此已缓存的 cwd 会保持陈旧，直到缓存条目被淘汰或提供方／运行时重新加载。
+- **失效由提供方驱动**：注册表没有 TTL，无法推断任意远程来源是否已发生变化；每个可变提供方都必须保留其注册作用域内的 `invalidate()` 能力，并由自身的观测机制调用它。
 - **提供方依次查询**：一个响应取消但速度缓慢的提供方会延迟之后注册的所有提供方；取消会停止调用方等待，但无法终止不响应取消的提供方持续运行的工作。
-- **提供方列表失败会使该请求无法使用整个来源**：注册表会记录并跳过该来源，不提供模型可见诊断或部分目录恢复契约。
+- **不保留不完整观测**：被拒绝的提供方会被省略，显式提供的候选项也仅在当前查找中可用；注册表既不负责上一份可用目录，也不负责逐提供方诊断。
 - **重复解析使用先到先得**：系统会记录并隐藏较晚出现的低优先级候选项；不提供检查全部被遮蔽定义的 API。

packages/skill/skill/src/index.ts

@@ -15,6 +15,7 @@ import type Schema from 'schemastery'
 
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 const DEFAULT_COLLECT_CACHE_ENTRIES = 128
+const MAX_COLLECT_ATTEMPTS = 2
 const RUNTIME_PROVIDER = 'runtime'
 const RUNTIME_RANK = 250
 
@@ -36,16 +37,24 @@ export type SkillResourceBase =
   | { readonly kind: 'url'; readonly url: string }
   | { readonly kind: 'opaque'; readonly description: string }
 
-/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
+/** Invocation controls shared by skill discovery consumers. */
+export interface SkillInvocationPolicy {
+  /** Whether model-facing catalogs and loaders include this skill. */
+  readonly modelInvocable: boolean
+  /** Whether human-facing command catalogs and loaders include this skill. */
+  readonly userInvocable: boolean
+}
+
+/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
 export interface SkillSummary {
-  /** Kebab-case identifier used with the `skill` tool. */
+  /** Kebab-case identifier used to address the skill. */
   readonly name: string
-  /** Short routing description shown to the model. */
+  /** Short routing description shown by discovery consumers. */
   readonly description: string
-  /** Optional extra routing guidance shown to the model. */
+  /** Optional extra routing guidance. */
   readonly whenToUse?: string
-  /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
-  readonly disableModelInvocation?: boolean
+  /** Resolved model and user invocation controls. */
+  readonly invocation: SkillInvocationPolicy
   /** Discovery source that produced this winning skill. */
   readonly source: SkillSource
   /** Provider that owns this skill body. */
@@ -77,7 +86,12 @@ export interface SkillDefinition extends SkillSummary {
 }
 
 /** Runtime skill contribution accepted by `ctx.skills.register()`. */
-export type SkillRegistration = Omit<SkillDefinition, 'provider'> & { readonly provider?: string }
+export type SkillRegistration = Omit<SkillDefinition, 'invocation' | 'provider'> & {
+  /** Invocation controls; omission permits both model and user surfaces. */
+  readonly invocation?: SkillInvocationPolicy
+  /** Provider label; omission uses the registry-owned runtime provider. */
+  readonly provider?: string
+}
 
 /** Caller context used for cwd-sensitive and abortable provider work. */
 export interface SkillLookupOptions {
@@ -87,6 +101,40 @@ export interface SkillLookupOptions {
   readonly signal?: AbortSignal | undefined
 }
 
+/**
+ * Return whether a skill may be advertised to and loaded by a model.
+ * @param skill - skill metadata carrying resolved invocation controls.
+ * @returns whether the policy permits model invocation.
+ */
+export function isModelInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean {
+  return skill.invocation.modelInvocable
+}
+
+/**
+ * Return whether a skill may be advertised to and loaded by a human-facing command.
+ * @param skill - skill metadata carrying resolved invocation controls.
+ * @returns whether the policy permits user invocation.
+ */
+export function isUserInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean {
+  return skill.invocation.userInvocable
+}
+
+/** One catalog observation plus whether discovery completed within a stable catalog revision. */
+export interface SkillCatalogSnapshot {
+  /** Sorted invocation-neutral summaries collected in this observation. */
+  readonly skills: SkillSummary[]
+  /** Whether every registered provider completed without a concurrent catalog revision. */
+  readonly complete: boolean
+}
+
+/** Provider candidates plus whether the current discovery is authoritative. */
+export interface SkillProviderObservation {
+  /** Candidates available from the current provider discovery. */
+  readonly candidates: readonly SkillCandidate[]
+  /** Whether discovery completed and these candidates may be cached. */
+  readonly complete: boolean
+}
+
 /** Provider interface for one source of skills, such as local directories or a remote registry. */
 export interface SkillProvider {
   /** Unique provider name in the `ctx.skills` registry. */
@@ -97,9 +145,10 @@ export interface SkillProvider {
    * authentication, and discovery are awaited inside this method. Implementations
    * should settle promptly when `options.signal` aborts.
    * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
-   * @returns provider candidates with precedence ranks and opaque locators.
+   * @returns provider candidates as a complete-array shorthand, or an explicit
+   *   observation when usable candidates came from incomplete discovery.
    */
-  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>
+  readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[] | SkillProviderObservation>
   /**
    * Load a complete skill body for a previously listed candidate.
    * @param candidate - the winning candidate originally returned by this provider.
@@ -109,6 +158,14 @@ export interface SkillProvider {
   readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
 }
 
+/** Registration-scoped lifecycle and invalidation capability borrowed by one provider. */
+export interface SkillProviderControl {
+  /** Aborts if registration fails or when the exact provider registration is disposed. */
+  readonly signal: AbortSignal
+  /** Invalidate completed catalogs and notify consumers only while the exact registration remains active. */
+  readonly invalidate: () => void
+}
+
 /** Skill registry configuration. */
 export interface Config {
   /** Maximum number of completed cwd/provider catalogs kept in memory. */
@@ -119,6 +176,17 @@ declare module 'cordis' {
   interface Context {
     skills: SkillService
   }
+
+  interface Events {
+    /**
+     * A skill provider, runtime contribution, or provider-backed catalog may
+     * have changed. This is an unfiltered invalidation notification; consumers
+     * refetch the catalog for their own lookup options. Listener failures are
+     * contained and cannot veto the registry mutation.
+     * @mode emit
+     */
+    'skills/change'(): void
+  }
 }
 
 interface IndexedCandidate {
@@ -135,7 +203,7 @@ interface CollectResult {
 
 /**
  * Registry of skill providers. It merges provider catalogs with stable
- * first-wins duplicate handling, exposes sorted model-visible summaries, and
+ * first-wins duplicate handling, exposes sorted invocation-neutral summaries, and
  * loads full skill bodies on demand.
  */
 export class SkillService extends Service {
@@ -145,7 +213,7 @@ export class SkillService extends Service {
 
   private readonly collectCacheMaxEntries: number
   private readonly providers = new Map<string, { provider: SkillProvider; order: number }>()
-  private readonly runtime = new Map<string, SkillRegistration>()
+  private readonly runtime = new Map<string, SkillDefinition>()
   private readonly collectCache = new Map<string, IndexedCandidate[]>()
   private providerRevision = 0
   private nextProviderOrder = 0
@@ -161,39 +229,57 @@ export class SkillService extends Service {
    * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
    * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
    * the provider and invalidates catalog caches.
-   * @param provider - the provider to register by `provider.name`.
+   * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
    * @returns the exact Cordis effect disposer that unregisters this provider;
    *   composite effects may yield it directly to preserve teardown ordering.
    */
-  registerProvider(provider: SkillProvider): () => void {
-    const name = provider.name
-    if (name === RUNTIME_PROVIDER) {
-      throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`)
+  registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void {
+    const lifecycle = new AbortController()
+    let active = false
+    let provider: SkillProvider
+    const control: SkillProviderControl = {
+      signal: lifecycle.signal,
+      invalidate: () => {
+        if (active) this.invalidateProvider(provider)
+      },
     }
-    if (this.providers.has(name)) {
-      throw new Error(`a skill provider named "${name}" is already registered`)
-    }
-    const providers = this.providers
-    const order = this.nextProviderOrder
-    const invalidateCache = (): void => { this.invalidateCache() }
-    this.nextProviderOrder += 1
-    const dispose = this.ctx.effect(function* () {
-      providers.set(name, { provider, order })
-      invalidateCache()
-      yield () => {
-        providers.delete(name)
-        invalidateCache()
+    try {
+      provider = create(control)
+      const name = provider.name
+      if (name === RUNTIME_PROVIDER) {
+        throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`)
       }
-    }, 'skills.registerProvider()')
-    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+      if (this.providers.has(name)) {
+        throw new Error(`a skill provider named "${name}" is already registered`)
+      }
+      const providers = this.providers
+      const order = this.nextProviderOrder
+      const invalidateCache = (): void => { this.invalidateCache() }
+      this.nextProviderOrder += 1
+      const dispose = this.ctx.effect(function* () {
+        active = true
+        providers.set(name, { provider, order })
+        invalidateCache()
+        yield () => {
+          active = false
+          providers.delete(name)
+          lifecycle.abort(new Error(`skill provider "${name}" disposed`))
+          invalidateCache()
+        }
+      }, 'skills.registerProvider()')
+      // oxlint-disable-next-line typescript/no-misused-promises -- synchronous cleanup; preserve exact disposer identity
+      return dispose
+    } catch (error) {
+      lifecycle.abort(error)
+      throw error
+    }
   }
 
   /**
    * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
    * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
    * receives a no-op disposer so it cannot remove the winner.
-   * @param skill - the complete skill definition to expose for discovery.
+   * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
    * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
    */
   register(skill: SkillRegistration): () => void {
@@ -203,15 +289,20 @@ export class SkillService extends Service {
       this.ctx.logger.warn(`runtime skill "${skill.name}" ignored because it is already registered`)
       return () => {}
     }
+    const definition: SkillDefinition = {
+      ...skill,
+      invocation: skill.invocation ?? { modelInvocable: true, userInvocable: true },
+      provider: skill.provider ?? RUNTIME_PROVIDER,
+    }
     const runtime = this.runtime
     const updateRevision = (): void => { this.runtimeRevision += 1 }
     const invalidateCache = (): void => { this.invalidateCache() }
     const dispose = this.ctx.effect(function* () {
-      runtime.set(skill.name, skill)
+      runtime.set(definition.name, definition)
       updateRevision()
       invalidateCache()
       yield () => {
-        runtime.delete(skill.name)
+        runtime.delete(definition.name)
         updateRevision()
         invalidateCache()
       }
@@ -221,18 +312,33 @@ export class SkillService extends Service {
   }
 
   /**
-   * List model-invocable skill summaries for a workspace. Lookup options and
-   * provider candidates are readonly same-process values borrowed throughout
-   * discovery.
+   * List invocation-neutral skill summaries for a workspace. Consumers apply
+   * model or user invocation policy at their operational boundary. Lookup
+   * options and provider candidates are readonly same-process values borrowed
+   * throughout discovery.
    * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
-   * @returns sorted summaries, excluding skills disabled for model invocation.
+   * @returns all sorted winning summaries.
    */
   async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]> {
-    return (await this.collect(options))
-      .map(entry => entry.candidate)
-      .filter(skill => skill.disableModelInvocation !== true)
-      .map(toSummary)
-      .sort(compareSkillSummary)
+    return (await this.snapshot(options)).skills
+  }
+
+  /**
+   * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+   * Incomplete observations are never cached, allowing consumers to retain last-good state and
+   * retry on their next request boundary.
+   * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+   * @returns sorted summaries plus discovery-completeness state.
+   */
+  async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot> {
+    const collected = await this.collect(options)
+    return {
+      skills: collected.entries
+        .map(entry => entry.candidate)
+        .map(toSummary)
+        .sort(compareSkillSummary),
+      complete: collected.cacheable,
+    }
   }
 
   /**
@@ -247,7 +353,7 @@ export class SkillService extends Service {
     if (!isSkillName(name)) return undefined
     const collected = await this.collect(options)
     throwIfAborted(options.signal)
-    const match = collected.find(entry => entry.candidate.name === name)
+    const match = collected.entries.find(entry => entry.candidate.name === name)
     if (match === undefined) return undefined
     const definition = await waitWithAbort(
       match.provider.get(match.candidate, options),
@@ -255,21 +361,32 @@ export class SkillService extends Service {
     )
     if (definition === undefined) return undefined
     validateDefinition(definition)
+    if (definition.name !== match.candidate.name) {
+      this.invalidateProvider(match.provider)
+      return undefined
+    }
     return definition
   }
 
-  private async collect(options: SkillLookupOptions): Promise<IndexedCandidate[]> {
+  private async collect(options: SkillLookupOptions): Promise<CollectResult> {
     throwIfAborted(options.signal)
+    let attempt = 1
     while (true) {
       const providerRevision = this.providerRevision
       const runtimeRevision = this.runtimeRevision
       const key = collectCacheKey(options, providerRevision, runtimeRevision)
       const cached = this.collectCache.get(key)
-      if (cached !== undefined) return cached
+      if (cached !== undefined) return { entries: cached, cacheable: true }
 
       const result = await this.collectFresh(options)
       throwIfAborted(options.signal)
-      if (providerRevision !== this.providerRevision || runtimeRevision !== this.runtimeRevision) continue
+      if (providerRevision !== this.providerRevision || runtimeRevision !== this.runtimeRevision) {
+        if (attempt < MAX_COLLECT_ATTEMPTS) {
+          attempt += 1
+          continue
+        }
+        return { entries: result.entries, cacheable: false }
+      }
       if (result.cacheable) {
         this.collectCache.set(key, result.entries)
         if (this.collectCache.size > this.collectCacheMaxEntries) {
@@ -277,7 +394,7 @@ export class SkillService extends Service {
           this.collectCache.delete(oldest.value)
         }
       }
-      return result.entries
+      return result
     }
   }
 
@@ -323,11 +440,9 @@ export class SkillService extends Service {
         this.ctx.logger.warn(`skill provider "${provider.name}" skipped: ${errorMessage(error)}`)
       }
       if (output === undefined) continue
-      if (!Array.isArray(output)) {
-        throw new TypeError(`skill provider "${provider.name}" list() must return an array`)
-      }
-      const listed = output as readonly SkillCandidate[]
-      for (const candidate of listed) {
+      const observation = normalizeProviderObservation(output, provider.name)
+      if (!observation.complete) cacheable = false
+      for (const candidate of observation.candidates) {
         validateCandidate(candidate, provider.name)
         candidates.push({ candidate, provider, providerOrder: order, localOrder })
         localOrder += 1
@@ -339,7 +454,45 @@ export class SkillService extends Service {
   private invalidateCache(): void {
     this.providerRevision += 1
     this.collectCache.clear()
+    this.notifyChange()
   }
+
+  private invalidateProvider(provider: SkillProvider): void {
+    /* v8 ignore else -- A definition load can outlive the exact provider registration it selected. */
+    if (this.providers.get(provider.name)?.provider === provider) this.invalidateCache()
+  }
+
+  /** Notify catalog observers without making their refresh work load-bearing. */
+  private notifyChange(): void {
+    for (const callback of this.ctx.events.dispatch('emit', ['skills/change'])) {
+      try {
+        const returned: unknown = callback()
+        void Promise.resolve(returned).catch((error: unknown) => {
+          this.ctx.logger.warn(`skills/change listener rejected: ${errorMessage(error)}`)
+        })
+      } catch (error: unknown) {
+        this.ctx.logger.warn(`skills/change listener threw: ${errorMessage(error)}`)
+      }
+    }
+  }
+}
+
+function normalizeProviderObservation(output: unknown, providerName: string): SkillProviderObservation {
+  if (Array.isArray(output)) {
+    return { candidates: output as readonly SkillCandidate[], complete: true }
+  }
+  if (output === null || typeof output !== 'object') {
+    throw invalidProviderObservation(providerName)
+  }
+  const observation = output as Partial<SkillProviderObservation>
+  if (!Array.isArray(observation.candidates) || typeof observation.complete !== 'boolean') {
+    throw invalidProviderObservation(providerName)
+  }
+  return observation as SkillProviderObservation
+}
+
+function invalidProviderObservation(providerName: string): TypeError {
+  return new TypeError(`skill provider "${providerName}" list() must return an array or { candidates, complete } observation`)
 }
 
 const RUNTIME_SKILL_PROVIDER: SkillProvider = {
@@ -349,19 +502,18 @@ const RUNTIME_SKILL_PROVIDER: SkillProvider = {
     return Promise.resolve([])
   },
   get(candidate) {
-    const skill = candidate.locator as SkillRegistration
-    return Promise.resolve({ ...skill, provider: skill.provider ?? RUNTIME_PROVIDER })
+    return Promise.resolve(candidate.locator as SkillDefinition)
   },
 }
 
-function runtimeCandidate(skill: SkillRegistration): SkillCandidate {
+function runtimeCandidate(skill: SkillDefinition): SkillCandidate {
   return {
     name: skill.name,
     description: skill.description,
     ...skill.whenToUse !== undefined ? { whenToUse: skill.whenToUse } : {},
-    ...skill.disableModelInvocation !== undefined ? { disableModelInvocation: skill.disableModelInvocation } : {},
+    invocation: skill.invocation,
     source: skill.source,
-    provider: skill.provider ?? RUNTIME_PROVIDER,
+    provider: skill.provider,
     ...skill.resourceBase !== undefined ? { resourceBase: skill.resourceBase } : {},
     rank: RUNTIME_RANK,
     locator: skill,
@@ -383,9 +535,7 @@ function validateCandidate(candidate: SkillCandidate, providerName: string): voi
   if (candidate.description.length === 0) {
     throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" without a description`)
   }
-  if (candidate.disableModelInvocation !== undefined && typeof candidate.disableModelInvocation !== 'boolean') {
-    throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-boolean disableModelInvocation`)
-  }
+  validateInvocation(candidate.invocation, `skill provider "${providerName}" returned skill "${candidate.name}"`)
   if (candidate.whenToUse !== undefined && typeof candidate.whenToUse !== 'string') {
     throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string whenToUse`)
   }
@@ -409,6 +559,7 @@ function validateCandidate(candidate: SkillCandidate, providerName: string): voi
 function validateRuntimeSkill(skill: SkillRegistration): void {
   if (!SKILL_NAME.test(skill.name)) throw new Error(`invalid skill name "${skill.name}"`)
   if (skill.description.length === 0) throw new Error(`skill "${skill.name}" requires a description`)
+  validateInvocation(skill.invocation, `runtime skill "${skill.name}"`)
 }
 
 /** Validate a definition loaded from a provider-controlled parser or remote source. */
@@ -416,7 +567,7 @@ function validateDefinition(skill: SkillDefinition): void {
   const name = skill.name
   const description = skill.description
   const whenToUse = skill.whenToUse
-  const disableModelInvocation = skill.disableModelInvocation
+  const invocation = skill.invocation
   const source = skill.source
   const provider = skill.provider
   const content = skill.content
@@ -425,9 +576,7 @@ function validateDefinition(skill: SkillDefinition): void {
   if (!SKILL_NAME.test(name)) throw new Error(`loaded skill has invalid name "${name}"`)
   if (typeof description !== 'string') throw new TypeError(`loaded skill "${name}" description must be a string`)
   if (description.length === 0) throw new Error(`loaded skill "${name}" requires a description`)
-  if (disableModelInvocation !== undefined && typeof disableModelInvocation !== 'boolean') {
-    throw new TypeError(`loaded skill "${name}" disableModelInvocation must be a boolean`)
-  }
+  validateInvocation(invocation, `loaded skill "${name}"`)
   if (whenToUse !== undefined && typeof whenToUse !== 'string') throw new TypeError(`loaded skill "${name}" whenToUse must be a string`)
   if (typeof source !== 'string') throw new TypeError(`loaded skill "${name}" source must be a string`)
   if (typeof provider !== 'string') throw new TypeError(`loaded skill "${name}" provider must be a string`)
@@ -436,18 +585,32 @@ function validateDefinition(skill: SkillDefinition): void {
 }
 
 function toSummary(skill: SkillDefinition | SkillCandidate): SkillSummary {
-  const { name, description, whenToUse, disableModelInvocation, source, provider, resourceBase } = skill
+  const { name, description, whenToUse, invocation, source, provider, resourceBase } = skill
   return {
     name,
     description,
     ...whenToUse !== undefined ? { whenToUse } : {},
-    ...disableModelInvocation !== undefined ? { disableModelInvocation } : {},
+    invocation,
     source,
     provider,
     ...resourceBase !== undefined ? { resourceBase } : {},
   }
 }
 
+function validateInvocation(invocation: unknown, subject: string): void {
+  if (invocation === undefined) return
+  if (typeof invocation !== 'object' || invocation === null || Array.isArray(invocation)) {
+    throw new TypeError(`${subject} with a non-object invocation policy`)
+  }
+  const policy = invocation as Record<string, unknown>
+  if (typeof policy.modelInvocable !== 'boolean') {
+    throw new TypeError(`${subject} with a non-boolean invocation.modelInvocable`)
+  }
+  if (typeof policy.userInvocable !== 'boolean') {
+    throw new TypeError(`${subject} with a non-boolean invocation.userInvocable`)
+  }
+}
+
 function compareSkillSummary(left: SkillSummary, right: SkillSummary): number {
   return compareCodePoints(left.name, right.name)
 }

packages/skill/skill/tests/skill.spec.ts

@@ -1,11 +1,21 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import SkillService, { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider } from '@deepseek-ai/dsh-skill'
+import SkillService, {
+  isModelInvocable,
+  isUserInvocable,
+  type SkillCandidate,
+  type SkillDefinition,
+  type SkillInvocationPolicy,
+  type SkillLookupOptions,
+  type SkillProvider,
+  type SkillProviderObservation,
+} from '@deepseek-ai/dsh-skill'
 
 function memorySkill(name: string, description: string, rank: number, body = `${name} body.`): SkillCandidate {
   return {
     name,
     description,
+    invocation: { modelInvocable: true, userInvocable: true },
     provider: 'memory',
     source: 'memory',
     rank,
@@ -34,6 +44,10 @@ class MemoryProvider implements SkillProvider {
   }
 }
 
+function registerProvider(ctx: Context, provider: SkillProvider): () => void {
+  return ctx.skills.registerProvider(() => provider)
+}
+
 describe('SkillService registry', () => {
   it('registers providers, resolves duplicates first-wins, and disposes providers', async () => {
     const ctx = new Context()
@@ -49,6 +63,7 @@ describe('SkillService registry', () => {
         return [{
           name: 'shadowed',
           description: 'Higher priority',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: 'override',
           source: 'override',
           rank: 5,
@@ -59,8 +74,8 @@ describe('SkillService registry', () => {
         return { ...candidate, content: (candidate.locator as { content: string }).content }
       },
     }
-    const disposeMemory = ctx.skills.registerProvider(provider)
-    ctx.skills.registerProvider(overrideProvider)
+    const disposeMemory = registerProvider(ctx, provider)
+    registerProvider(ctx, overrideProvider)
 
     expect((await ctx.skills.list()).map(skill => [skill.name, skill.description, skill.provider])).toEqual([
       ['a-skill', 'A skill', 'memory'],
@@ -74,6 +89,7 @@ describe('SkillService registry', () => {
         return [{
           name: 'same-rank-skill',
           description: 'Same rank',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: 'same-rank',
           source: 'same-rank',
           rank: 10,
@@ -84,40 +100,96 @@ describe('SkillService registry', () => {
         return { ...candidate, content: (candidate.locator as { content: string }).content }
       },
     }
-    ctx.skills.registerProvider(sameRankProvider)
+    registerProvider(ctx, sameRankProvider)
     expect((await ctx.skills.list()).find(skill => skill.name === 'same-rank-skill')?.provider).toBe('same-rank')
     await expect(ctx.plugin({
       name: 'duplicate-memory',
       inject: ['skills'],
       apply(pluginCtx: Context) {
-        pluginCtx.skills.registerProvider(new MemoryProvider([]))
+        registerProvider(pluginCtx, new MemoryProvider([]))
       },
     })).rejects.toThrow('already registered')
-    expect(() => ctx.skills.registerProvider({
-      name: 'runtime',
-      async list() {
-        return []
-      },
-      async get() {
-        return undefined
-      },
+    let rejectedSignal: AbortSignal | undefined
+    expect(() => ctx.skills.registerProvider((control) => {
+      rejectedSignal = control.signal
+      return {
+        name: 'runtime',
+        async list() {
+          return []
+        },
+        async get() {
+          return undefined
+        },
+      }
     })).toThrow('reserved')
+    expect(rejectedSignal?.aborted).toBe(true)
+
+    const factoryFailure = new Error('factory failed')
+    let failedSignal: AbortSignal | undefined
+    expect(() => ctx.skills.registerProvider((control) => {
+      failedSignal = control.signal
+      throw factoryFailure
+    })).toThrow(factoryFailure)
+    expect(failedSignal?.reason).toBe(factoryFailure)
+
+    const effectContext = new Context()
+    const effectService = new SkillService(effectContext)
+    const effectFailure = new Error('effect registration failed')
+    vi.spyOn(effectContext, 'effect').mockImplementation(() => { throw effectFailure })
+    let effectSignal: AbortSignal | undefined
+    expect(() => effectService.registerProvider((control) => {
+      effectSignal = control.signal
+      return {
+        name: 'effect-provider',
+        list: () => Promise.resolve([]),
+        get: () => Promise.resolve(undefined),
+      }
+    })).toThrow(effectFailure)
+    expect(effectSignal?.reason).toBe(effectFailure)
 
     disposeMemory()
     expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['same-rank-skill', 'shadowed'])
   })
 
+  it('returns an invocation-neutral catalog and resolves model and user policy independently', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const registrations = [
+      { name: 'both', invocation: undefined },
+      { name: 'model-only', invocation: { modelInvocable: true, userInvocable: false } },
+      { name: 'user-only', invocation: { modelInvocable: false, userInvocable: true } },
+      { name: 'trusted-only', invocation: { modelInvocable: false, userInvocable: false } },
+    ] as const
+    for (const registration of registrations) {
+      ctx.skills.register({
+        name: registration.name,
+        description: registration.name,
+        source: 'runtime',
+        ...registration.invocation === undefined ? {} : { invocation: registration.invocation },
+        content: `${registration.name} body.`,
+      })
+    }
+
+    const listed = await ctx.skills.list()
+    expect(listed.map(skill => skill.name)).toEqual(['both', 'model-only', 'trusted-only', 'user-only'])
+    expect(listed.find(skill => skill.name === 'both')?.invocation).toEqual({ modelInvocable: true, userInvocable: true })
+    expect(listed.filter(isModelInvocable).map(skill => skill.name)).toEqual(['both', 'model-only'])
+    expect(listed.filter(isUserInvocable).map(skill => skill.name)).toEqual(['both', 'user-only'])
+    expect(await ctx.skills.get('trusted-only')).toMatchObject({ content: 'trusted-only body.' })
+    expect((await ctx.skills.get('both'))?.invocation).toEqual({ modelInvocable: true, userInvocable: true })
+  })
+
   it('validates parsed candidate fields', async () => {
     const ctx = new Context()
     await ctx.plugin(SkillService)
     const badDescription = { value: 'object-description' }
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'bad-candidate',
       list: () => Promise.resolve([{
         ...memorySkill('bad-candidate', 'placeholder', 1),
         provider: 'bad-candidate',
         description: badDescription as unknown as string,
-        disableModelInvocation: 'false' as unknown as boolean,
+        invocation: { modelInvocable: false, userInvocable: true },
       }]),
       get: () => Promise.resolve(undefined),
     })
@@ -125,27 +197,30 @@ describe('SkillService registry', () => {
 
     const badBoolean = new Context()
     await badBoolean.plugin(SkillService)
-    badBoolean.skills.registerProvider({
+    registerProvider(badBoolean, {
       name: 'bad-boolean',
       list: () => Promise.resolve([{
         ...memorySkill('bad-boolean', 'Bad boolean', 1),
         provider: 'bad-boolean',
-        disableModelInvocation: 'false' as unknown as boolean,
+        invocation: { modelInvocable: 'false' as unknown as boolean, userInvocable: true },
       }]),
       get: () => Promise.resolve(undefined),
     })
-    await expect(badBoolean.skills.list()).rejects.toThrow('non-boolean disableModelInvocation')
+    await expect(badBoolean.skills.list()).rejects.toThrow('non-boolean invocation.modelInvocable')
   })
 
-  it('rejects non-array provider results and every malformed candidate scalar', async () => {
-    const badList = new Context()
-    await badList.plugin(SkillService)
-    badList.skills.registerProvider({
-      name: 'non-array-list',
-      list: () => Promise.resolve({} as unknown as SkillCandidate[]),
-      get: () => Promise.resolve(undefined),
-    })
-    await expect(badList.skills.list()).rejects.toThrow('list() must return an array')
+  it('rejects malformed provider results and every malformed candidate scalar', async () => {
+    const malformedOutputs: unknown[] = [null, 1, {}, { candidates: [], complete: 'yes' }]
+    for (const [index, output] of malformedOutputs.entries()) {
+      const badList = new Context()
+      await badList.plugin(SkillService)
+      registerProvider(badList, {
+        name: `malformed-list-${index}`,
+        list: () => Promise.resolve(output as readonly SkillCandidate[] | SkillProviderObservation),
+        get: () => Promise.resolve(undefined),
+      })
+      await expect(badList.skills.list()).rejects.toThrow('list() must return an array or { candidates, complete } observation')
+    }
 
     const cases: { patch: Partial<SkillCandidate>; expected: string }[] = [
       { patch: { name: { value: 'candidate' } as unknown as string }, expected: 'non-string skill name' },
@@ -163,7 +238,7 @@ describe('SkillService registry', () => {
         name: `candidate-${index}`,
         description: 'Candidate',
         whenToUse: 'Use this candidate.',
-        disableModelInvocation: false,
+        invocation: { modelInvocable: true, userInvocable: true },
         provider: providerName,
         source: 'test',
         rank: 1,
@@ -171,7 +246,7 @@ describe('SkillService registry', () => {
         path: '/skills/candidate/SKILL.md',
         ...patch,
       } as SkillCandidate
-      ctx.skills.registerProvider({
+      registerProvider(ctx, {
         name: providerName,
         list: () => Promise.resolve([candidate]),
         get: () => Promise.resolve(undefined),
@@ -190,12 +265,13 @@ describe('SkillService registry', () => {
     const candidate: SkillCandidate = {
       name: 'skill-a',
       description: 'Skill A',
+      invocation: { modelInvocable: true, userInvocable: true },
       provider: 'contextual',
       source: 'test',
       rank: 1,
       locator: 'skill-a',
     }
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'contextual',
       async list(received) {
         listedWith = received
@@ -218,12 +294,13 @@ describe('SkillService registry', () => {
     const ctx = new Context()
     await ctx.plugin(SkillService)
     let getCalls = 0
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'cached',
       async list() {
         return [{
           name: 'cached-skill',
           description: 'Cached skill',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: 'cached',
           source: 'test',
           rank: 1,
@@ -261,18 +338,20 @@ describe('SkillService registry', () => {
         resolve({
           name: 'held-skill',
           description: 'Held skill',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: 'held',
           source: 'test',
           content: 'Held body.',
         })
       }
     })
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'held',
       async list() {
         return [{
           name: 'held-skill',
           description: 'Held skill',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: 'held',
           source: 'test',
           rank: 1,
@@ -320,11 +399,12 @@ describe('SkillService registry', () => {
     const ctx = new Context()
     await ctx.plugin(SkillService)
     const locator = { id: 'provider-owned' }
+    const invocation = { modelInvocable: true, userInvocable: true }
     const candidate: SkillCandidate = {
       name: 'stable-skill',
       description: 'Stable description',
       whenToUse: 'When stability matters.',
-      disableModelInvocation: false,
+      invocation,
       provider: 'detached',
       source: 'test',
       resourceBase: { kind: 'opaque', description: 'candidate resources' },
@@ -337,7 +417,7 @@ describe('SkillService registry', () => {
       name: 'stable-skill',
       description: 'Stable description',
       whenToUse: 'When stability matters.',
-      disableModelInvocation: false,
+      invocation,
       provider: 'detached',
       source: 'test',
       resourceBase: { kind: 'opaque', description: 'definition resources' },
@@ -347,7 +427,7 @@ describe('SkillService registry', () => {
     }
     let listCalls = 0
     let received: SkillCandidate | undefined
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'detached',
       async list() {
         listCalls += 1
@@ -366,6 +446,7 @@ describe('SkillService registry', () => {
       resourceBase: { kind: 'opaque', description: 'candidate resources' },
     })])
     expect(listed[0]?.resourceBase).toBe(candidate.resourceBase)
+    expect(listed[0]?.invocation).toBe(invocation)
     expect(listCalls).toBe(1)
 
     const loaded = await ctx.skills.get('stable-skill')
@@ -379,11 +460,12 @@ describe('SkillService registry', () => {
     await ctx.plugin(SkillService)
     const resourceBase = { kind: 'opaque' as const, description: 'runtime resources' }
     const metadata = { owner: 'runtime' }
+    const invocation = { modelInvocable: true, userInvocable: true }
     const registration = {
       name: 'runtime-skill',
       description: 'Runtime',
       whenToUse: 'When runtime data is needed.',
-      disableModelInvocation: false,
+      invocation,
       source: 'runtime',
       resourceBase,
       metadata,
@@ -399,6 +481,7 @@ describe('SkillService registry', () => {
     const listed = await ctx.skills.list()
     const loaded = await ctx.skills.get('runtime-skill')
     expect(listed[0]?.resourceBase).toBe(resourceBase)
+    expect(listed[0]?.invocation).toBe(invocation)
     expect(loaded?.resourceBase).toBe(resourceBase)
     expect(loaded?.metadata).toBe(metadata)
     expect(loaded?.provider).toBe('runtime')
@@ -410,7 +493,23 @@ describe('SkillService registry', () => {
       { patch: { name: 'Bad_Name' }, expected: 'loaded skill has invalid name' },
       { patch: { description: { value: 'description' } as unknown as string }, expected: 'description must be a string' },
       { patch: { description: '' }, expected: 'requires a description' },
-      { patch: { disableModelInvocation: 'false' as unknown as boolean }, expected: 'disableModelInvocation must be a boolean' },
+      { patch: { invocation: null as never }, expected: 'non-object invocation policy' },
+      {
+        patch: { invocation: { modelInvocable: 'false' as unknown as boolean, userInvocable: true } },
+        expected: 'invocation.modelInvocable',
+      },
+      {
+        patch: { invocation: { modelInvocable: true, userInvocable: 'true' as unknown as boolean } },
+        expected: 'invocation.userInvocable',
+      },
+      {
+        patch: { invocation: { userInvocable: true } as unknown as SkillInvocationPolicy },
+        expected: 'invocation.modelInvocable',
+      },
+      {
+        patch: { invocation: { modelInvocable: true } as unknown as SkillInvocationPolicy },
+        expected: 'invocation.userInvocable',
+      },
       { patch: { whenToUse: 1 as unknown as string }, expected: 'whenToUse must be a string' },
       { patch: { source: { value: 'source' } as unknown as string }, expected: 'source must be a string' },
       { patch: { provider: { value: 'provider' } as unknown as string }, expected: 'provider must be a string' },
@@ -422,11 +521,12 @@ describe('SkillService registry', () => {
       await ctx.plugin(SkillService)
       const providerName = `definition-provider-${index}`
       const skillName = `definition-${index}`
-      ctx.skills.registerProvider({
+      registerProvider(ctx, {
         name: providerName,
         list: () => Promise.resolve([{
           name: skillName,
           description: 'Candidate',
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: providerName,
           source: 'test',
           rank: 1,
@@ -436,7 +536,7 @@ describe('SkillService registry', () => {
           name: skillName,
           description: 'Definition',
           whenToUse: 'Use this definition.',
-          disableModelInvocation: false,
+          invocation: { modelInvocable: true, userInvocable: true },
           provider: providerName,
           source: 'test',
           content: 'Definition body.',
@@ -455,7 +555,7 @@ describe('SkillService registry', () => {
 
     const ctx = new Context()
     await ctx.plugin(SkillService)
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'bad',
       async list() {
         return [memorySkill('Bad_Name', 'bad', 1)]
@@ -474,7 +574,7 @@ describe('SkillService registry', () => {
     for (const candidate of invalidCandidates) {
       const invalid = new Context()
       await invalid.plugin(SkillService)
-      invalid.skills.registerProvider({
+      registerProvider(invalid, {
         name: candidate.name,
         async list() {
           return [candidate]
@@ -492,7 +592,7 @@ describe('SkillService registry', () => {
   it('sorts model-visible summaries without locale-sensitive collation', async () => {
     const ctx = new Context()
     await ctx.plugin(SkillService)
-    ctx.skills.registerProvider(new MemoryProvider([
+    registerProvider(ctx, new MemoryProvider([
       memorySkill('z-skill', 'Z skill', 10),
       memorySkill('a-skill', 'A skill', 10),
     ]))
@@ -517,7 +617,7 @@ describe('SkillService registry', () => {
     const ctx = new Context()
     await ctx.plugin(SkillService, { collectCacheMaxEntries: 1 })
     const provider = new MemoryProvider([memorySkill('first-skill', 'First', 10)])
-    ctx.skills.registerProvider(provider)
+    registerProvider(ctx, provider)
 
     expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill'])
     provider.replace([memorySkill('second-skill', 'Second', 10)])
@@ -544,7 +644,7 @@ describe('SkillService registry', () => {
 
     let fail = true
     let flakyCalls = 0
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'flaky',
       async list() {
         flakyCalls += 1
@@ -555,7 +655,9 @@ describe('SkillService registry', () => {
         return undefined
       },
     })
-    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill'])
+    const incomplete = await ctx.skills.snapshot()
+    expect(incomplete.skills.map(skill => skill.name)).toEqual(['second-skill'])
+    expect(incomplete.complete).toBe(false)
     expect(flakyCalls).toBe(1)
     expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill'])
     expect(flakyCalls).toBe(2)
@@ -566,6 +668,231 @@ describe('SkillService registry', () => {
     expect(flakyCalls).toBe(3)
   })
 
+  it('keeps candidates from incomplete provider observations loadable without caching them', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let listCalls = 0
+    registerProvider(ctx, {
+      name: 'incomplete-candidates',
+      async list() {
+        listCalls += 1
+        return {
+          candidates: [{ ...memorySkill('available-skill', 'Available', 10), provider: 'incomplete-candidates' }],
+          complete: false,
+        }
+      },
+      async get(candidate) {
+        return { ...candidate, content: (candidate.locator as { content: string }).content }
+      },
+    })
+
+    expect(await ctx.skills.snapshot()).toMatchObject({
+      skills: [{ name: 'available-skill' }],
+      complete: false,
+    })
+    expect((await ctx.skills.get('available-skill'))?.content).toBe('available-skill body.')
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['available-skill'])
+    expect(listCalls).toBe(3)
+  })
+
+  it('invalidates only the exact registered provider and ignores its late callbacks', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const provider = new MemoryProvider([memorySkill('first-skill', 'First', 10)])
+    let invalidate = (): void => {}
+    let signal: AbortSignal | undefined
+    const dispose = ctx.skills.registerProvider((control) => {
+      invalidate = control.invalidate
+      signal = control.signal
+      return provider
+    })
+
+    expect((await ctx.skills.snapshot()).complete).toBe(true)
+    provider.replace([memorySkill('second-skill', 'Second', 10)])
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['first-skill'])
+
+    invalidate()
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['second-skill'])
+    dispose()
+    expect(signal?.aborted).toBe(true)
+
+    const replacement = new MemoryProvider([memorySkill('replacement-skill', 'Replacement', 10)])
+    registerProvider(ctx, replacement)
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['replacement-skill'])
+    invalidate()
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['replacement-skill'])
+    expect(replacement.listCalls).toBe(1)
+  })
+
+  it('emits catalog invalidations for live provider and runtime mutations', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const provider = new MemoryProvider([memorySkill('provider-skill', 'Provider', 10)])
+    let changes = 0
+    ctx.on('skills/change', () => { changes += 1 })
+
+    let invalidate = (): void => {}
+    const disposeProvider = ctx.skills.registerProvider((control) => {
+      invalidate = control.invalidate
+      return provider
+    })
+    expect(changes).toBe(1)
+    invalidate()
+    expect(changes).toBe(2)
+
+    const disposeRuntime = ctx.skills.register({
+      name: 'runtime-skill',
+      description: 'Runtime',
+      source: 'runtime',
+      content: 'Runtime body.',
+    })
+    expect(changes).toBe(3)
+    disposeRuntime()
+    expect(changes).toBe(4)
+    disposeProvider()
+    expect(changes).toBe(5)
+    invalidate()
+    expect(changes).toBe(5)
+  })
+
+  it('contains synchronous and asynchronous catalog observer failures', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+    const disposeThrowing = ctx.on('skills/change', () => { throw new Error('observer threw') })
+    // oxlint-disable-next-line typescript/no-misused-promises -- deliberate rejection proves notification containment
+    const disposeRejecting = ctx.on('skills/change', () => Promise.reject(new Error('observer rejected')))
+    let observed = 0
+    const disposeObserver = ctx.on('skills/change', () => { observed += 1 })
+
+    const provider = new MemoryProvider([])
+    expect(() => registerProvider(ctx, provider)).not.toThrow()
+    await Promise.resolve()
+    expect(observed).toBe(1)
+    expect(warnings).toEqual([
+      'skills/change listener threw: Error: observer threw',
+      'skills/change listener rejected: Error: observer rejected',
+    ])
+
+    disposeThrowing()
+    disposeRejecting()
+    disposeObserver()
+  })
+
+  it('retries an in-flight catalog invalidated by its provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let release: (() => void) | undefined
+    const started = Promise.withResolvers<undefined>()
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const provider = new MemoryProvider([memorySkill('stale-skill', 'Stale', 10)])
+    const originalList = provider.list.bind(provider)
+    provider.list = async (options) => {
+      if (provider.listCalls === 0) {
+        provider.listCalls += 1
+        started.resolve(undefined)
+        await gate
+        return [memorySkill('stale-skill', 'Stale', 10)]
+      }
+      return await originalList(options)
+    }
+    let invalidate = (): void => {}
+    ctx.skills.registerProvider((control) => {
+      invalidate = control.invalidate
+      return provider
+    })
+
+    const pending = ctx.skills.list()
+    await started.promise
+    provider.replace([memorySkill('fresh-skill', 'Fresh', 10)])
+    invalidate()
+    release?.()
+
+    expect((await pending).map(skill => skill.name)).toEqual(['fresh-skill'])
+    expect(provider.listCalls).toBe(2)
+  })
+
+  it('bounds repeated in-flight invalidation and leaves the result uncached', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let listCalls = 0
+    ctx.skills.registerProvider(control => ({
+      name: 'self-invalidating',
+      async list() {
+        listCalls += 1
+        control.invalidate()
+        return [{
+          ...memorySkill('bounded-skill', `Attempt ${listCalls}`, 10),
+          provider: 'self-invalidating',
+        }]
+      },
+      async get() {
+        return undefined
+      },
+    }))
+
+    expect(await ctx.skills.snapshot()).toEqual({
+      skills: [{
+        name: 'bounded-skill',
+        description: 'Attempt 2',
+        invocation: { modelInvocable: true, userInvocable: true },
+        provider: 'self-invalidating',
+        source: 'memory',
+      }],
+      complete: false,
+    })
+    expect(listCalls).toBe(2)
+
+    expect((await ctx.skills.snapshot()).skills[0]?.description).toBe('Attempt 4')
+    expect(listCalls).toBe(4)
+  })
+
+  it('invalidates a provider whose loaded definition changed identity', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    let listCalls = 0
+    const provider: SkillProvider = {
+      name: 'renamed',
+      async list() {
+        listCalls += 1
+        return [{
+          name: 'old-name',
+          description: 'Old name',
+          invocation: { modelInvocable: true, userInvocable: true },
+          provider: 'renamed',
+          source: 'test',
+          rank: 1,
+          locator: 'old-name',
+        }]
+      },
+      async get(candidate) {
+        return { ...candidate, name: 'new-name', content: 'Fresh body.' }
+      },
+    }
+    registerProvider(ctx, provider)
+
+    expect(await ctx.skills.get('old-name')).toBeUndefined()
+    await ctx.skills.list()
+    expect(listCalls).toBe(2)
+  })
+
+  it('returns undefined when a discovered candidate disappears before loading', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    registerProvider(ctx, {
+      name: 'vanished-body',
+      async list() {
+        return [{ ...memorySkill('vanished-skill', 'Vanished', 10), provider: 'vanished-body' }]
+      },
+      async get() {
+        return undefined
+      },
+    })
+
+    await expect(ctx.skills.get('vanished-skill')).resolves.toBeUndefined()
+  })
+
   it('contains a provider rejection whose string coercion throws', async () => {
     const ctx = new Context()
     await ctx.plugin(SkillService)
@@ -576,7 +903,7 @@ describe('SkillService registry', () => {
         throw new Error('provider failure coercion failed')
       },
     }
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'hostile-failure',
       list() {
         // Deliberately violate the provider contract to prove containment is total.
@@ -601,7 +928,7 @@ describe('SkillService registry', () => {
     let release: (() => void) | undefined
     const started = new Promise<void>((resolve) => { markStarted = resolve })
     const gate = new Promise<void>((resolve) => { release = resolve })
-    const dispose = ctx.skills.registerProvider({
+    const dispose = registerProvider(ctx, {
       name: 'delayed',
       async list() {
         markStarted?.()
@@ -631,7 +958,7 @@ describe('SkillService registry', () => {
     const held = new Promise<SkillCandidate[]>((resolve) => {
       release = () => { resolve([]) }
     })
-    ctx.skills.registerProvider({
+    registerProvider(ctx, {
       name: 'uncooperative',
       list(options) {
         seenSignal = options.signal
@@ -668,6 +995,13 @@ describe('SkillService registry', () => {
     await ctx.plugin(SkillService)
     expect(() => ctx.skills.register({ name: 'Bad_Name', description: 'Bad', source: 'runtime', content: 'bad' })).toThrow('invalid skill name')
     expect(() => ctx.skills.register({ name: 'no-description', description: '', source: 'runtime', content: 'bad' })).toThrow('requires a description')
+    expect(() => ctx.skills.register({
+      name: 'bad-invocation',
+      description: 'Bad invocation',
+      source: 'runtime',
+      invocation: [] as never,
+      content: 'bad',
+    })).toThrow('non-object invocation policy')
     expect(await ctx.skills.get('missing-skill')).toBeUndefined()
     expect(await ctx.skills.get('Bad_Name')).toBeUndefined()