@vellumai/assistant 0.3.3 → 0.3.5

package/src/config/vellum-skills/slack-oauth-setup/SKILL.md

@@ -12,7 +12,7 @@ You are helping your user create a Slack App and OAuth credentials so the Messag
 
 ## Prerequisites
 
-Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+Before starting, check that `ingress.publicBaseUrl` is configured (`INGRESS_PUBLIC_BASE_URL` env var or workspace config). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
 
 ## Before You Start
 
@@ -89,7 +89,7 @@ Tell the user: "Permissions configured! Now let's set up the redirect URL and ge
 
 Navigate to the "OAuth & Permissions" page if not already there.
 
-The redirect URL must point to the gateway's OAuth callback endpoint. Determine the URL by reading the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable. The callback path is `/webhooks/oauth/callback`.
+The redirect URL must point to the gateway's OAuth callback endpoint. Determine the URL by reading the `ingress.publicBaseUrl` value from the assistant's workspace config or the `INGRESS_PUBLIC_BASE_URL` environment variable. The callback path is `/webhooks/oauth/callback`.
 
 In the "Redirect URLs" section:
 1. Click "Add New Redirect URL"
@@ -98,7 +98,7 @@ In the "Redirect URLs" section:
 
 Take a `browser_snapshot` to confirm.
 
-Tell the user: "Redirect URL configured. Make sure your tunnel is running and `ingress.publicBaseUrl` is set in Settings so the callback can reach the gateway."
+Tell the user: "Redirect URL configured. Make sure your tunnel is running and `ingress.publicBaseUrl` is set so the callback can reach the gateway. You can always check or update this from the Settings page."
 
 ## Step 5: Extract Client ID and Client Secret
 

package/src/config/vellum-skills/sms-setup/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: "SMS Setup"
+description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
+user-invocable: true
+metadata: {"vellum": {"emoji": "\ud83d\udce8"}}
+---
+
+You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow.
+
+## Step 1: Check Channel Readiness
+
+First, check the current SMS channel readiness state by sending the `channel_readiness` IPC message:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "get",
+  "channel": "sms"
+}
+```
+
+Inspect the `channel_readiness_response`. The response contains `snapshots` with each channel's readiness state.
+
+- If the SMS channel shows `ready: true` and all `localChecks` pass, skip to Step 3.
+- If any local checks fail, proceed to Step 2 to fix the baseline.
+
+## Step 2: Establish Baseline (Twilio Setup)
+
+If SMS baseline is not ready (missing credentials, phone number, or ingress), load the `twilio-setup` skill to walk the user through the basics:
+
+```
+skill_load skill=twilio-setup
+```
+
+Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."*
+
+After twilio-setup completes, re-check readiness:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms"
+}
+```
+
+If baseline is still not ready, report the specific failures and ask the user to address them before continuing.
+
+## Step 3: Remote Compliance Check
+
+Once baseline is ready, run a full readiness check including remote (Twilio API) checks:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms",
+  "includeRemote": true
+}
+```
+
+Examine the remote check results:
+- If all remote checks pass, proceed to Step 4.
+- If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow:
+  1. Check compliance status using the `twilio_config` IPC with `action: "sms_compliance_status"` (if available).
+  2. If toll-free verification is needed, collect user information and submit via `twilio_config` with `action: "sms_submit_tollfree_verification"`.
+  3. Report verification status and next steps.
+
+**Note:** Compliance actions (sms_compliance_status, sms_submit_tollfree_verification, etc.) may not be available yet. If the IPC action is not recognized, tell the user: *"Compliance automation isn't available yet. You may need to check Twilio Console manually for toll-free verification status."*
+
+### Data Collection for Verification (Individual-First)
+
+When collecting information for toll-free verification:
+- Assume the user is an **individual / sole proprietor** by default
+- Do NOT ask for EIN, business registration number, or business registration authority
+- Explain that Twilio labels some fields as "business" fields even for individual submitters
+- Only collect what's required: business name (can be personal name), website (can be personal site), notification email, use case, message samples, opt-in info
+- If Twilio rejects the submission requiring business registration, explain the situation and guide through the fallback path
+
+## Step 4: Test Send
+
+Run a test SMS to verify end-to-end delivery:
+
+Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"*
+
+After the user provides a number, send a test message using the messaging tools:
+- Use `messaging_send` with `platform: "sms"`, `conversation_id: "<phone number>"`, and a test message like "Test SMS from your Vellum assistant."
+- Report the result honestly:
+  - If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes."*
+  - If the send fails: report the error and suggest troubleshooting steps
+
+## Step 5: Final Status Report
+
+After completing (or skipping) the test, present a clear summary:
+
+**If everything passed:**
+*"SMS is ready! Here's your setup status:"*
+- Twilio credentials: configured
+- Phone number: {number}
+- Ingress: configured
+- Compliance: {status}
+- Test send: {result}
+
+**If there are blockers:**
+*"SMS setup is partially complete. Here's what still needs attention:"*
+- List each blocker with the specific next action
+
+## Troubleshooting
+
+If the user returns to this skill after initial setup:
+1. Always start with Step 1 (readiness check) to assess current state
+2. Skip steps that are already complete
+3. Focus on the specific issue the user is experiencing
+
+Common issues:
+- **"Messages not delivering"** — Check compliance status, verify the number isn't flagged
+- **"Twilio error on send"** — Check credentials, phone number assignment, and ingress
+- **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -103,12 +103,17 @@ Before reporting success, confirm the guardian binding was actually created. Sen
 
 ### Step 8: Report Success
 
+First, retrieve the bot identity by sending a `telegram_config` IPC message with `action: "get"` and reading the `botUsername` field from the response.
+
 Summarize what was done:
+- Bot identity: @{botUsername}
 - Bot verified and credentials stored securely via daemon
 - Webhook registration: handled automatically by the gateway
 - Bot commands registered: /new, /guardian_verify
-- Guardian identity verified (if completed and binding confirmed)
+- Guardian identity: {verified | not configured}
+- Guardian verification status: {verified via challenge | skipped}
 - Routing configuration validated
+- To re-check guardian status later, send `guardian_verification` with `action: "status"` and `channel: "telegram"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

package/src/config/vellum-skills/twilio-setup/SKILL.md

@@ -18,6 +18,27 @@ This skill manages the full Twilio lifecycle:
 
 All operations go through the `twilio_config` IPC handler on the daemon, which validates inputs, stores credentials securely, and manages phone number state.
 
+### Multi-Assistant Setups
+
+In a multi-assistant environment (multiple assistants sharing the same daemon), some `twilio_config` actions are **assistant-scoped** while others are **global** (shared across all assistants):
+
+**Global actions** (ignore `assistantId` — credentials are shared across all assistants):
+- `set_credentials` — Stores Account SID and Auth Token in global secure storage (`credential:twilio:*` keys). All assistants share the same Twilio account credentials.
+- `clear_credentials` — Removes the globally stored Account SID and Auth Token. This affects all assistants.
+
+**Assistant-scoped actions** (use `assistantId` to scope phone number configuration per assistant):
+- `get` — Returns the phone number assigned to the specified assistant (falls back to the legacy global number if no per-assistant mapping exists).
+- `assign_number` — Assigns a phone number to a specific assistant via the per-assistant mapping.
+- `provision_number` — Provisions a new number and assigns it to the specified assistant.
+- `list_numbers` — Lists all phone numbers on the shared Twilio account (uses global credentials).
+
+Include `assistantId` in assistant-scoped actions whenever:
+- Multiple assistants share the same Twilio account but use different phone numbers
+- You want to ensure configuration changes only affect a specific assistant
+- The user has explicitly selected or referenced a particular assistant
+
+All IPC examples below include the optional `assistantId` field in assistant-scoped actions. Omit it in single-assistant setups. For global actions (`set_credentials`, `clear_credentials`), the `assistantId` field is accepted but ignored.
+
 ## Step 1: Check Current Configuration
 
 First, check whether Twilio is already configured by sending the `twilio_config` IPC message with `action: "get"`:
@@ -25,7 +46,8 @@ First, check whether Twilio is already configured by sending the `twilio_config`
 ```json
 {
   "type": "twilio_config",
-  "action": "get"
+  "action": "get",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -62,6 +84,8 @@ After both credentials are collected, retrieve them from secure storage and pass
 
 Both `accountSid` and `authToken` are required — the daemon validates the credentials against the Twilio API before storing them. If credentials are invalid, the daemon returns an error. Tell the user and ask them to re-enter via the secure prompt.
 
+**Note:** `set_credentials` is a global operation — credentials are stored once and shared across all assistants. The `assistantId` field is accepted but ignored.
+
 ## Step 3: Get a Phone Number
 
 The assistant needs a phone number to make calls and send SMS. There are two paths:
@@ -75,7 +99,8 @@ If the user wants to buy a new number through Twilio, send:
   "type": "twilio_config",
   "action": "provision_number",
   "areaCode": "415",
-  "country": "US"
+  "country": "US",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -100,7 +125,8 @@ If the user already has a Twilio phone number, first list available numbers:
 ```json
 {
   "type": "twilio_config",
-  "action": "list_numbers"
+  "action": "list_numbers",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -112,7 +138,8 @@ Then assign the chosen number:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -132,7 +159,8 @@ Then assign it through the IPC:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -171,6 +199,46 @@ Confirm:
 
 Tell the user: **"Twilio is configured. Your assistant's phone number is {phoneNumber}. This number is used for both voice calls and SMS messaging."**
 
+## Step 5.5: Guardian Verification (SMS)
+
+Now link the user's phone number as the trusted SMS guardian for this assistant. Tell the user: "Now let's verify your guardian identity for SMS. This links your phone number as the trusted guardian for SMS messaging."
+
+1. Send the `guardian_verification` IPC message with `action: "create_challenge"` and `channel: "sms"`:
+
+```json
+{
+  "type": "guardian_verification",
+  "action": "create_challenge",
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
+}
+```
+
+2. The daemon returns a `guardian_verification_response` with `success: true`, `secret`, and `instruction`. Display the instruction to the user. It will look like: "Send `/guardian_verify <secret>` to your bot via SMS within 10 minutes."
+
+3. Wait for the user to confirm they have sent the verification code via SMS to the assistant's phone number.
+
+4. Check verification status by sending `guardian_verification` with `action: "status"` and `channel: "sms"`:
+
+```json
+{
+  "type": "guardian_verification",
+  "action": "status",
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
+}
+```
+
+5. If `bound` is `true`: "Guardian verified! Your phone number is now the trusted SMS guardian."
+
+6. If `bound` is `false` and the user claims they sent the code: "The verification doesn't appear to have succeeded. Let's generate a new challenge." Repeat from substep 1.
+
+**Note:** Guardian verification is optional but recommended. If the user declines or wants to skip, proceed to Step 6 without blocking.
+
+To re-check guardian status later, send `guardian_verification` with `action: "status"` and `channel: "sms"`.
+
+Report the guardian verification result: **"Guardian identity: {verified | not configured}."**
+
 ## Step 6: Enable Features
 
 Now that Twilio is configured, the user can enable the features that depend on it:
@@ -194,7 +262,9 @@ If the user wants to disconnect Twilio, send:
 }
 ```
 
-This removes the stored Account SID and Auth Token. Your phone number assignment will be preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+This removes the stored Account SID and Auth Token. Phone number assignments are preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+
+**Note:** `clear_credentials` is a global operation — it removes credentials for all assistants, not just the current one. The `assistantId` field is accepted but ignored. In multi-assistant setups, warn the user that clearing credentials will affect all assistants sharing this Twilio account.
 
 ## Troubleshooting
 

package/src/daemon/auth-manager.ts

@@ -0,0 +1,103 @@
+/**
+ * Manages daemon-level authentication: session token lifecycle,
+ * per-socket auth state, and auth timeouts.
+ */
+import * as net from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { getSessionTokenPath } from '../util/platform.js';
+import { hasNoAuthOverride } from './connection-policy.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('auth-manager');
+
+export const AUTH_TIMEOUT_MS = 5_000;
+
+export class AuthManager {
+  private sessionToken = '';
+  private authenticatedSockets = new Set<net.Socket>();
+  private authTimeouts = new Map<net.Socket, ReturnType<typeof setTimeout>>();
+
+  /** Initialize the session token — reuse from disk or generate a new one. */
+  initToken(): void {
+    const tokenPath = getSessionTokenPath();
+    let existingToken: string | null = null;
+    try {
+      const raw = readFileSync(tokenPath, 'utf-8').trim();
+      if (raw.length >= 32) existingToken = raw;
+    } catch { /* file doesn't exist yet */ }
+
+    if (existingToken) {
+      this.sessionToken = existingToken;
+      log.info({ tokenPath }, 'Reusing existing session token');
+    } else {
+      this.sessionToken = randomBytes(32).toString('hex');
+      writeFileSync(tokenPath, this.sessionToken, { mode: 0o600 });
+      chmodSync(tokenPath, 0o600);
+      log.info({ tokenPath }, 'New session token generated');
+    }
+  }
+
+  isAuthenticated(socket: net.Socket): boolean {
+    return this.authenticatedSockets.has(socket);
+  }
+
+  /** Returns true if VELLUM_DAEMON_NOAUTH bypass is active. */
+  shouldAutoAuth(): boolean {
+    return hasNoAuthOverride();
+  }
+
+  markAuthenticated(socket: net.Socket): void {
+    this.authenticatedSockets.add(socket);
+  }
+
+  /** Validate a token and authenticate the socket. Returns true on success. */
+  authenticate(socket: net.Socket, token: string): boolean {
+    if (token === this.sessionToken) {
+      this.authenticatedSockets.add(socket);
+      return true;
+    }
+    log.warn('Client provided invalid auth token');
+    return false;
+  }
+
+  /** Start the auth timeout for a newly connected socket. */
+  startTimeout(socket: net.Socket, onTimeout: () => void): void {
+    const timer = setTimeout(() => {
+      if (!this.authenticatedSockets.has(socket)) {
+        log.warn('Client failed to authenticate within timeout, disconnecting');
+        onTimeout();
+      }
+    }, AUTH_TIMEOUT_MS);
+    this.authTimeouts.set(socket, timer);
+  }
+
+  /** Clear the auth timeout (called when the first message arrives). */
+  clearTimeout(socket: net.Socket): void {
+    const timer = this.authTimeouts.get(socket);
+    if (timer) {
+      clearTimeout(timer);
+      this.authTimeouts.delete(socket);
+    }
+  }
+
+  /** Remove all auth state for a disconnected socket. */
+  cleanupSocket(socket: net.Socket): void {
+    this.clearTimeout(socket);
+    this.authenticatedSockets.delete(socket);
+  }
+
+  /** Tear down all auth state on server stop. */
+  cleanupAll(): void {
+    for (const timer of this.authTimeouts.values()) {
+      clearTimeout(timer);
+    }
+    this.authTimeouts.clear();
+    this.authenticatedSockets.clear();
+  }
+
+  /** Iterate over authenticated sockets (for broadcasting). */
+  getAuthenticatedSockets(): Set<net.Socket> {
+    return this.authenticatedSockets;
+  }
+}

package/src/daemon/computer-use-session.ts

@@ -897,7 +897,14 @@ export class ComputerUseSession {
     decision: UserDecision,
     selectedPattern?: string,
     selectedScope?: string,
+    decisionContext?: string,
   ): void {
-    this.prompter?.resolveConfirmation(requestId, decision, selectedPattern, selectedScope);
+    this.prompter?.resolveConfirmation(
+      requestId,
+      decision,
+      selectedPattern,
+      selectedScope,
+      decisionContext,
+    );
   }
 }

package/src/daemon/config-watcher.ts

@@ -0,0 +1,253 @@
+/**
+ * File watchers and config reload logic extracted from DaemonServer.
+ * Watches workspace files (config, prompts), protected directory
+ * (trust rules, secret allowlist), and skills directories for changes.
+ */
+import { existsSync, readdirSync, watch, type FSWatcher } from 'node:fs';
+import { join } from 'node:path';
+import { getRootDir, getWorkspaceDir, getWorkspaceSkillsDir } from '../util/platform.js';
+import { getConfig, invalidateConfigCache } from '../config/loader.js';
+import { initializeProviders } from '../providers/registry.js';
+import { clearCache as clearTrustCache } from '../permissions/trust-store.js';
+import { resetAllowlist, validateAllowlistFile } from '../security/secret-allowlist.js';
+import { clearEmbeddingBackendCache } from '../memory/embedding-backend.js';
+import { DebouncerMap } from '../util/debounce.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('config-watcher');
+
+export class ConfigWatcher {
+  private watchers: FSWatcher[] = [];
+  private debounceTimers = new DebouncerMap({
+    defaultDelayMs: 200,
+    maxEntries: 1000,
+    protectedKeyPrefix: '__',
+  });
+  private suppressReload = false;
+  private lastFingerprint = '';
+  private lastRefreshTime = 0;
+
+  static readonly REFRESH_INTERVAL_MS = 30_000;
+
+  /** Expose the debounce timers so handlers can schedule debounced work. */
+  get timers(): DebouncerMap {
+    return this.debounceTimers;
+  }
+
+  get suppressConfigReload(): boolean {
+    return this.suppressReload;
+  }
+
+  set suppressConfigReload(value: boolean) {
+    this.suppressReload = value;
+  }
+
+  get lastConfigRefreshTime(): number {
+    return this.lastRefreshTime;
+  }
+
+  set lastConfigRefreshTime(value: number) {
+    this.lastRefreshTime = value;
+  }
+
+  /** Compute a fingerprint of the current config for change detection. */
+  configFingerprint(config: ReturnType<typeof getConfig>): string {
+    return JSON.stringify(config);
+  }
+
+  /** Initialize the config fingerprint (call after first config load). */
+  initFingerprint(config: ReturnType<typeof getConfig>): void {
+    this.lastFingerprint = this.configFingerprint(config);
+  }
+
+  /** Update the fingerprint to match the current config. */
+  updateFingerprint(): void {
+    this.lastFingerprint = this.configFingerprint(getConfig());
+    this.lastRefreshTime = Date.now();
+  }
+
+  /**
+   * Reload config from disk + secure storage, and refresh providers only
+   * when effective config values (including API keys) have changed.
+   * Returns true if config actually changed.
+   */
+  refreshConfigFromSources(): boolean {
+    invalidateConfigCache();
+    const config = getConfig();
+    const fingerprint = this.configFingerprint(config);
+    if (fingerprint === this.lastFingerprint) {
+      return false;
+    }
+    clearTrustCache();
+    clearEmbeddingBackendCache();
+    const isFirstInit = this.lastFingerprint === '';
+    initializeProviders(config);
+    this.lastFingerprint = fingerprint;
+    return !isFirstInit;
+  }
+
+  /**
+   * Start all file watchers. `onSessionEvict` is called when watched
+   * files change and sessions need to be evicted for reload.
+   */
+  start(onSessionEvict: () => void): void {
+    const workspaceDir = getWorkspaceDir();
+    const protectedDir = join(getRootDir(), 'protected');
+
+    const workspaceHandlers: Record<string, () => void> = {
+      'config.json': () => {
+        if (this.suppressReload) return;
+        try {
+          const changed = this.refreshConfigFromSources();
+          if (changed) onSessionEvict();
+        } catch (err) {
+          log.error({ err, configPath: join(workspaceDir, 'config.json') }, 'Failed to reload config after file change. Previous config remains active.');
+        }
+      },
+      'SOUL.md': () => onSessionEvict(),
+      'IDENTITY.md': () => onSessionEvict(),
+      'USER.md': () => onSessionEvict(),
+      'LOOKS.md': () => onSessionEvict(),
+    };
+
+    const protectedHandlers: Record<string, () => void> = {
+      'trust.json': () => {
+        clearTrustCache();
+      },
+      'secret-allowlist.json': () => {
+        resetAllowlist();
+        try {
+          const errors = validateAllowlistFile();
+          if (errors && errors.length > 0) {
+            for (const e of errors) {
+              log.warn({ index: e.index, pattern: e.pattern }, `Invalid regex in secret-allowlist.json: ${e.message}`);
+            }
+          }
+        } catch (err) {
+          log.warn({ err }, 'Failed to validate secret-allowlist.json');
+        }
+      },
+    };
+
+    const watchDir = (dir: string, handlers: Record<string, () => void>, label: string): void => {
+      try {
+        const watcher = watch(dir, (_eventType, filename) => {
+          if (!filename) return;
+          const file = String(filename);
+          if (!handlers[file]) return;
+          this.debounceTimers.schedule(`file:${file}`, () => {
+            log.info({ file }, 'File changed, reloading');
+            handlers[file]();
+          });
+        });
+        this.watchers.push(watcher);
+        log.info({ dir }, `Watching ${label}`);
+      } catch (err) {
+        log.warn({ err, dir }, `Failed to watch ${label}. Hot-reload will be unavailable.`);
+      }
+    };
+
+    watchDir(workspaceDir, workspaceHandlers, 'workspace directory for config/prompt changes');
+    if (existsSync(protectedDir)) {
+      watchDir(protectedDir, protectedHandlers, 'protected directory for trust/allowlist changes');
+    }
+
+    this.startSkillsWatchers(onSessionEvict);
+  }
+
+  stop(): void {
+    this.debounceTimers.cancelAll();
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+  }
+
+  private startSkillsWatchers(onSessionEvict: () => void): void {
+    const skillsDir = getWorkspaceSkillsDir();
+    if (!existsSync(skillsDir)) return;
+
+    const scheduleSkillsReload = (file: string): void => {
+      this.debounceTimers.schedule(`skills:${file}`, () => {
+        log.info({ file }, 'Skill file changed, reloading');
+        onSessionEvict();
+      });
+    };
+
+    try {
+      const recursiveWatcher = watch(skillsDir, { recursive: true }, (_eventType, filename) => {
+        scheduleSkillsReload(filename ? String(filename) : '(unknown)');
+      });
+      this.watchers.push(recursiveWatcher);
+      log.info({ dir: skillsDir }, 'Watching skills directory recursively');
+      return;
+    } catch (err) {
+      log.info({ err, dir: skillsDir }, 'Recursive skills watch unavailable; using per-directory watchers');
+    }
+
+    const childWatchers = new Map<string, FSWatcher>();
+
+    const watchDir = (dirPath: string, onChange: (filename: string) => void): FSWatcher | null => {
+      try {
+        const watcher = watch(dirPath, (_eventType, filename) => {
+          onChange(filename ? String(filename) : '(unknown)');
+        });
+        this.watchers.push(watcher);
+        return watcher;
+      } catch (err) {
+        log.warn({ err, dirPath }, 'Failed to watch skills directory');
+        return null;
+      }
+    };
+
+    const removeWatcher = (watcher: FSWatcher): void => {
+      const idx = this.watchers.indexOf(watcher);
+      if (idx !== -1) {
+        this.watchers.splice(idx, 1);
+      }
+    };
+
+    const refreshChildWatchers = (): void => {
+      const nextChildDirs = new Set<string>();
+
+      try {
+        const entries = readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          const childDir = join(skillsDir, entry.name);
+          nextChildDirs.add(childDir);
+
+          if (childWatchers.has(childDir)) continue;
+
+          const watcher = watchDir(childDir, (filename) => {
+            const label = filename === '(unknown)' ? entry.name : `${entry.name}/${filename}`;
+            scheduleSkillsReload(label);
+          });
+          if (watcher) {
+            childWatchers.set(childDir, watcher);
+          }
+        }
+      } catch (err) {
+        log.warn({ err, skillsDir }, 'Failed to enumerate skill directories');
+        return;
+      }
+
+      for (const [childDir, watcher] of childWatchers.entries()) {
+        if (nextChildDirs.has(childDir)) continue;
+        watcher.close();
+        childWatchers.delete(childDir);
+        removeWatcher(watcher);
+      }
+    };
+
+    const rootWatcher = watchDir(skillsDir, (filename) => {
+      scheduleSkillsReload(filename);
+      refreshChildWatchers();
+    });
+
+    if (!rootWatcher) return;
+
+    refreshChildWatchers();
+    log.info({ dir: skillsDir }, 'Watching skills directory with non-recursive fallback');
+  }
+}