@notis_ai/cli 0.2.0-beta.153.2 → 0.2.0-beta.155.1

package/src/runtime/app-dev-build-supervisor.js

@@ -0,0 +1,47 @@
+// A separate process retains ownership of the build group if the CLI crashes.
+// IPC disconnect is the lifetime signal; unlike polling a PID it cannot mistake
+// a reused PID for the original owner.
+import { spawn } from 'node:child_process';
+
+if (!process.send) throw new Error('Build supervisor requires an IPC owner');
+let build;
+let stopping = false;
+function stop(code = 0) {
+  if (stopping) return;
+  stopping = true;
+  if (!build?.pid) process.exit(code);
+  if (process.platform === 'win32') {
+    const killer = spawn('taskkill', ['/pid', String(build.pid), '/t', '/f']);
+    killer.once('error', () => process.exit(1));
+    killer.once('exit', () => process.exit(code));
+    return;
+  }
+  const signalGroup = (signal) => {
+    try { process.kill(-build.pid, signal); } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  };
+  signalGroup('SIGTERM');
+  // npm can exit before Vite/esbuild. Keep the supervisor alive until the
+  // entire group has received the fallback signal.
+  setTimeout(() => {
+    signalGroup('SIGKILL');
+    process.exit(code);
+  }, 1000);
+}
+process.on('disconnect', () => stop());
+process.on('SIGTERM', () => stop());
+process.on('SIGINT', () => stop());
+process.once('message', ({ command, args }) => {
+  if (stopping || !process.connected) return;
+  build = spawn(command, args, {
+    detached: process.platform !== 'win32',
+    stdio: 'inherit',
+    env: process.env,
+  });
+  build.once('spawn', () => {
+    if (process.connected) process.send({ pid: build.pid }, () => {});
+  });
+  build.once('error', () => stop(1));
+  build.once('exit', (code) => stop(code || 0));
+});

package/src/runtime/app-dev-build.js

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { fileURLToPath } from 'node:url';
+
+// Expose the actual npm group identity so Desktop recovery and diagnostics
+// retain their existing ownership contract. The supervisor owns its lifetime.
+export async function startAppDevBuild(cwd, command = 'npm', args = ['run', 'build', '--', '--watch']) {
+  const supervisor = spawn(process.execPath, [fileURLToPath(new URL('./app-dev-build-supervisor.js', import.meta.url))], {
+    cwd,
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: '1', NOTIS_DEV: '1' },
+  });
+  const build = new EventEmitter();
+  build.pid = null;
+  build.exitCode = null;
+  build.signalCode = null;
+  build.kill = (signal = 'SIGTERM') => supervisor.kill(signal);
+  await new Promise((resolve, reject) => {
+    supervisor.once('error', reject);
+    supervisor.once('exit', (code, signal) => {
+      build.exitCode = code;
+      build.signalCode = signal;
+      reject(new Error(`Build supervisor exited before startup (${code ?? signal})`));
+      build.emit('exit', code, signal);
+    });
+    supervisor.once('message', ({ pid }) => {
+      build.pid = pid;
+      resolve();
+    });
+    supervisor.send({ command, args }, (error) => { if (error) reject(error); });
+  });
+  return build;
+}
+
+export async function stopAppDevBuild(build) {
+  if (!build || build.exitCode !== null || build.signalCode !== null) return;
+  await new Promise((resolve) => {
+    build.once('exit', resolve);
+    build.kill('SIGTERM');
+  });
+}

package/src/runtime/app-dev-server.js

@@ -44,6 +44,7 @@ import {
   readAppDevSessions,
 } from './app-dev-sessions.js';
 import { captureDesktopWatcherOwnership } from './app-dev-process-identity.js';
+import { startAppDevBuild } from './app-dev-build.js';
 
 const CONTENT_TYPES = {
   '.js': 'application/javascript; charset=utf-8',
@@ -1007,12 +1008,7 @@ export async function startAppDevServer({
       watchManifestInputs(state);
       pollForBundleAndWatch(state);
 
-      const buildProcess = spawn('npm', ['run', 'build', '--', '--watch'], {
-        cwd: state.projectDir,
-        detached: process.platform !== 'win32',
-        stdio: 'inherit',
-        env: { ...process.env, NOTIS_DEV: '1' },
-      });
+      const buildProcess = await startAppDevBuild(state.projectDir);
       state.buildProcess = buildProcess;
       for (let attempt = 0; attempt < 5 && !state.watcherOwnership; attempt += 1) {
         state.watcherOwnership = captureDesktopWatcherOwnership({

package/src/runtime/profiles.js

@@ -485,10 +485,15 @@ export function updateConfig(updater) {
 }
 
 /**
- * Remove only worktree-owned profiles without normalizing the rest of the
- * shared file. Archive cleanup can run before a packaged Desktop upgrade has
- * migrated its legacy `jwt`; preserving unknown/raw fields here keeps that
- * migrate-then-strip handoff intact.
+ * Remove every profile owned by one worktree, plus stale localhost stubs that
+ * use one of that worktree's generated profile names. Older builds sometimes
+ * lost `dev_workspace_root`, so requiring the ownership marker alone leaves a
+ * dead local profile behind after archive.
+ *
+ * Do this without normalizing the rest of the shared file. Archive cleanup can
+ * run before a packaged Desktop upgrade has migrated its legacy `jwt`;
+ * preserving unknown/raw fields here keeps that migrate-then-strip handoff
+ * intact.
  */
 export function removeOwnedDevProfiles(profileNames, workspaceRoot) {
   return withConfigWriteLock((configFile) => {
@@ -502,16 +507,19 @@ export function removeOwnedDevProfiles(profileNames, workspaceRoot) {
       return [];
     }
 
+    const generatedNames = new Set(profileNames);
     const removed = [];
-    for (const name of profileNames) {
-      const profile = Object.hasOwn(raw.profiles, name) ? raw.profiles[name] : null;
-      if (
-        !profile
-        || typeof profile !== 'object'
-        || profile.dev_workspace_root !== workspaceRoot
-      ) {
+    for (const [name, profile] of Object.entries(raw.profiles)) {
+      if (!profile || typeof profile !== 'object') {
         continue;
       }
+
+      const ownedByWorkspace = profile.dev_workspace_root === workspaceRoot;
+      const staleGeneratedLocalProfile = generatedNames.has(name)
+        && !profile.dev_workspace_root
+        && isLocalApiBase(profile.api_base);
+      if (!ownedByWorkspace && !staleGeneratedLocalProfile) continue;
+
       delete raw.profiles[name];
       removed.push(name);
       if (raw.current_profile === name) raw.current_profile = DEFAULT_PROFILE;

package/src/runtime/skill-sync/cloud-client.ts

@@ -72,13 +72,15 @@ export async function updateAgentTargets(
   serverUrl: string,
   jwt: string,
   skillId: string,
-  targets: AgentTargets,
-): Promise<{ success: boolean; agent_targets: AgentTargets }> {
-  return requestJson<{ success: boolean; agent_targets: AgentTargets }>(`${serverUrl}/portal_skills/agent-targets`, jwt, {
+  targets: Partial<AgentTargets>,
+  expectedUpdatedAt?: string,
+): Promise<{ success: boolean; agent_targets: AgentTargets; updated_at?: string }> {
+  return requestJson<{ success: boolean; agent_targets: AgentTargets; updated_at?: string }>(`${serverUrl}/portal_skills/agent-targets`, jwt, {
     method: 'PATCH',
     body: {
       skill_id: skillId,
       agent_targets: targets,
+      ...(expectedUpdatedAt ? { expected_updated_at: expectedUpdatedAt } : {}),
     },
   });
 }

package/src/runtime/skill-sync/index.ts

@@ -1,4 +1,5 @@
 import type {
+  AgentTargets,
   LocalSkill,
   NotisSyncState,
   SkillSyncFailure,
@@ -49,6 +50,7 @@ export interface RunSkillSyncResult {
   /** Skills the server rejected (e.g. an invalid SKILL.md description). The rest of
    * the batch still syncs; these are surfaced so the user knows what to fix. */
   failedPushes: SkillSyncFailure[];
+  failedLinks?: SkillSyncFailure[];
 }
 
 export interface RunSkillSyncOptions {
@@ -81,6 +83,7 @@ export interface MaterializeCloudSkillsResult {
   deleted: number;
   removed: number;
   lastSyncedAt: string | null;
+  failedLinks?: SkillSyncFailure[];
 }
 
 export interface MaterializeCloudSkillsOptions {
@@ -174,6 +177,7 @@ function buildSyncState(
   pullResponse: SyncPullResponse,
   localSkills: LocalSkill[],
   lastSyncedAt: string | null,
+  verifiedAgentLinks: Record<string, Partial<AgentTargets>> = {},
 ): NotisSyncState {
   const localSkillMap = toSkillMap(localSkills);
   const skills = Object.fromEntries(
@@ -185,6 +189,8 @@ function buildSyncState(
           cloudId: skill.id,
           folderHash: localSkill?.folderHash || skill.skill_folder_hash || "",
           agentTargets: normalizeAgentTargets(skill.agent_targets),
+          verifiedAgentLinks: skill.status === "active" ? verifiedAgentLinks[skill.name] ?? {} : {},
+          cloudUpdatedAt: skill.updated_at,
           syncedAt: lastSyncedAt || new Date().toISOString(),
         },
       ];
@@ -268,6 +274,7 @@ async function writePulledSkillsToScopedMirror(
     RunSkillSyncDependencies,
     "downloadSkillBundle" | "writeCloudSkillToDisk"
   >,
+  failures: SkillSyncFailure[] = [],
 ): Promise<number> {
   const localSkillMap = toSkillMap(localSkills);
   const warnSkillSync = (message: string, error: unknown): void => {
@@ -289,6 +296,8 @@ async function writePulledSkillsToScopedMirror(
       })
     ) {
       downloaded += 1;
+    } else {
+      failures.push({ name: cloudSkill.name, error: "Skill content could not be downloaded or written; sync will retry" });
     }
   }
 
@@ -346,27 +355,44 @@ export async function materializeCloudSkillsForLocalShell(
   const previousState = await deps.readSyncState(syncPaths);
 
   const localSkills = await deps.scanLocalSkills(syncPaths);
+  const failedDownloads: SkillSyncFailure[] = [];
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
     previousState,
     syncPaths,
     deps,
+    failedDownloads,
   );
   const finalLocalSkills = await deps.scanLocalSkills(syncPaths);
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
 
   const relinkSkillNames = new Set(options.relinkSkillNames || []);
+  const failures = [...failedDownloads];
+  const verifiedLinks: Record<string, Partial<AgentTargets>> = {};
+  for (const skill of pullResponse.skills) {
+    const previous = previousState.skills[skill.name];
+    if (skill.updated_at && previous?.cloudId === skill.id && previous.cloudUpdatedAt === skill.updated_at) {
+      verifiedLinks[skill.name] = { ...previous.verifiedAgentLinks };
+    }
+  }
   if (relinkSkillNames.size > 0) {
-    await deps.syncSymlinks(
+    const relinked = await deps.syncSymlinks(
       pullResponse.skills.filter((skill) => relinkSkillNames.has(skill.name)),
       syncPaths.skillsDir,
       { removeUndesired: false },
     );
+    failures.push(...(relinked.failures ?? []).filter(
+      (failure) => !failedDownloads.some((download) => download.name === failure.name),
+    ));
+    for (const name of relinkSkillNames) {
+      verifiedLinks[name] = relinked.verifiedAgentLinks?.[name] ?? {};
+    }
   }
+  for (const failure of failedDownloads) delete verifiedLinks[failure.name];
 
   await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt),
+    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks),
     syncPaths,
   );
 
@@ -376,6 +402,7 @@ export async function materializeCloudSkillsForLocalShell(
     deleted: 0,
     removed: 0,
     lastSyncedAt,
+    ...(failures.length ? { failedLinks: failures } : {}),
   };
 }
 
@@ -397,6 +424,7 @@ async function deactivateDeletedAgentSkills(
     RunSkillSyncDependencies,
     "detectDeletedAgentSymlinks" | "updateAgentTargets" | "pullSkills"
   >,
+  failures: SkillSyncFailure[],
 ): Promise<number> {
   // First sync (incl. legacy migration) has no reliable "we created this link" signal, so we
   // cannot tell a user deletion apart from a never-created link — skip detection entirely.
@@ -413,34 +441,6 @@ async function deactivateDeletedAgentSkills(
     return 0;
   }
 
-  // The agent-targets endpoint replaces the whole agent_targets column, so re-read the freshest
-  // values right before writing and merge onto them, only flipping the deleted agent. This avoids
-  // clobbering a concurrent portal/other-desktop change to a DIFFERENT agent with the stale
-  // snapshot from the top-of-sync pull. (A narrow read-modify-write window remains; the endpoint
-  // has no partial update.)
-  const latestSkillsById = new Map(pullResponse.skills.map((skill) => [skill.id, skill]));
-  let fresh: SyncPullResponse | null = null;
-  try {
-    fresh = await deps.pullSkills(serverUrl, jwt);
-  } catch (error) {
-    console.warn(
-      "[skill-sync] Could not re-pull latest agent targets before deactivation; " +
-        "using the top-of-sync snapshot.",
-      error,
-    );
-  }
-  if (fresh) {
-    // A transport failure may fall back to the already-authorized snapshot, but
-    // an explicit legacy denial must abort before any server or local mutation.
-    assertSkillsPullAuthorized(fresh);
-    for (const skill of fresh.skills) {
-      latestSkillsById.set(skill.id, skill);
-    }
-  }
-
-  // Group deletions by skill so multiple deleted agents for the SAME skill are flipped in one
-  // PATCH. Otherwise each PATCH, rebuilt from the same snapshot, would overwrite the previous one
-  // (deleting both claude_code and cursor for one skill would otherwise leave only the last off).
   const agentsBySkill = new Map<string, { skillName: string; agents: Set<DeletedAgentSymlink["agent"]> }>();
   for (const deletion of deletions) {
     const entry = agentsBySkill.get(deletion.skillId) ?? {
@@ -451,33 +451,39 @@ async function deactivateDeletedAgentSkills(
     agentsBySkill.set(deletion.skillId, entry);
   }
 
-  const inMemoryById = new Map(pullResponse.skills.map((skill) => [skill.id, skill]));
+  const fresh = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
+  assertSkillsPullAuthorized(fresh);
+  Object.assign(pullResponse, fresh);
+  let needsRefresh = false;
   let deactivated = 0;
   for (const [skillId, { skillName, agents }] of agentsBySkill) {
-    const latest = latestSkillsById.get(skillId);
-    if (!latest) {
-      continue;
-    }
-    const nextTargets = { ...normalizeAgentTargets(latest.agent_targets) };
-    for (const agent of agents) {
-      nextTargets[agent] = false;
-    }
+    const skill = pullResponse.skills.find((item) => item.id === skillId);
+    const previous = previousState.skills[skillName];
+    if (!skill?.updated_at || previous?.cloudUpdatedAt !== skill.updated_at) continue;
+    const patch = Object.fromEntries([...agents].map((agent) => [agent, false]));
     try {
-      await deps.updateAgentTargets(serverUrl, jwt, skillId, nextTargets);
-      // Mutate the in-memory pull response so the symlink passes below see the link as undesired.
-      const inMemory = inMemoryById.get(skillId);
-      if (inMemory) {
-        inMemory.agent_targets = nextTargets;
+      const saved = await deps.updateAgentTargets(serverUrl, jwt, skillId, patch, skill.updated_at);
+      if (saved.success !== true || !saved.updated_at?.trim()
+        || saved.updated_at === skill.updated_at
+        || !['notis', 'claude_code', 'cursor', 'codex'].every((agent) =>
+          typeof saved.agent_targets?.[agent as keyof AgentTargets] === 'boolean')
+        || ![...agents].every((agent) => saved.agent_targets[agent] === false)) {
+        throw new Error('Assignment update did not return a verified saved revision');
       }
+      skill.agent_targets = saved.agent_targets;
+      skill.updated_at = saved.updated_at;
       deactivated += agents.size;
     } catch (error) {
-      console.warn(
-        `[skill-sync] Failed to deactivate "${skillName}" for ${[...agents].join(", ")} ` +
-          `after local symlink deletion:`,
-        error,
-      );
+      needsRefresh = true;
+      failures.push({ name: skillName, error: 'Could not save the local agent removal; refreshed saved assignments' });
+      console.warn(`[skill-sync] Assignment changed or could not be saved for "${skillName}"; refreshing before reconciliation.`, error);
     }
   }
+  if (needsRefresh) {
+    const refreshed = withoutBaseSkills(await deps.pullSkills(serverUrl, jwt));
+    assertSkillsPullAuthorized(refreshed);
+    Object.assign(pullResponse, refreshed);
+  }
   return deactivated;
 }
 
@@ -535,6 +541,13 @@ export async function runSkillSync(
       .map((skill) => skill.name),
   );
   const protectedSkillNames = new Set([...cloudCuratedSkillNames, ...BASE_SKILL_NAMES]);
+  const scopedState = withoutBaseSkillState(await deps.readSyncState(syncPaths));
+  const assignmentFailures: SkillSyncFailure[] = [];
+  const deactivated = syncSettings.agent_targets_conditional_updates === true
+    ? await deactivateDeletedAgentSkills(
+        serverUrl, jwt, pullResponse, scopedState, scopedState, syncPaths.skillsDir, deps, assignmentFailures,
+      )
+    : 0;
   const authUserId = decodeJwtSubject(jwt);
   let previousAuthState: NotisSyncState | null = null;
   if (authUserId && authUserId !== syncUserId) {
@@ -550,7 +563,6 @@ export async function runSkillSync(
   });
   const localSkills = (await deps.scanLocalSkills(syncPaths))
     .filter((skill) => !BASE_SKILL_NAMES.has(skill.name));
-  const scopedState = withoutBaseSkillState(await deps.readSyncState(syncPaths));
   const previousState = withoutBaseSkillState(applyLegacyFirstRunState(
     localSkills,
     scopedState,
@@ -560,18 +572,7 @@ export async function runSkillSync(
           : previousAuthState)
       : null,
   ));
-  // Honor locally-deleted per-agent symlinks as deactivations before reconciling, otherwise the
-  // first syncSymlinks pass would recreate the link the user just deleted.
-  const deactivated = await deactivateDeletedAgentSkills(
-    serverUrl,
-    jwt,
-    pullResponse,
-    previousState,
-    scopedState,
-    syncPaths.skillsDir,
-    deps,
-  );
-  await deps.syncSymlinks(
+  const gatheredSymlinkResult = await deps.syncSymlinks(
     buildLocalSymlinkCandidates(pullResponse, localSkills, previousState),
     syncPaths.skillsDir,
   );
@@ -607,12 +608,14 @@ export async function runSkillSync(
     }
   }
 
+  const failedDownloads: SkillSyncFailure[] = [];
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
     previousState,
     syncPaths,
     deps,
+    failedDownloads,
   );
 
   const finalLocalSkills = (await deps.scanLocalSkills(syncPaths))
@@ -621,10 +624,12 @@ export async function runSkillSync(
     buildLocalSymlinkCandidates(pullResponse, finalLocalSkills, previousState),
     syncPaths.skillsDir,
   );
+  const verifiedLinks = { ...(symlinkResult.verifiedAgentLinks ?? {}) };
+  for (const failure of failedDownloads) delete verifiedLinks[failure.name];
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
 
   await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt),
+    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks),
     syncPaths,
   );
 
@@ -635,9 +640,12 @@ export async function runSkillSync(
     downloaded,
     deleted,
     deactivated,
-    linked: symlinkResult.linked,
-    removed: foreignLinksRemoved + symlinkResult.removed,
+    linked: gatheredSymlinkResult.linked + symlinkResult.linked,
+    removed: foreignLinksRemoved + gatheredSymlinkResult.removed + symlinkResult.removed,
     skipped: symlinkResult.skipped,
+    failedLinks: [...assignmentFailures, ...failedDownloads, ...(symlinkResult.failures ?? []).filter(
+      (failure) => !failedDownloads.some((download) => download.name === failure.name),
+    )],
     lastSyncedAt,
     failedPushes,
   };

package/src/runtime/skill-sync/symlink-manager.ts

@@ -8,7 +8,7 @@ import {
   NOTIS_SKILL_SYNC_ROOT,
   safeName,
 } from './local-scanner';
-import { normalizeAgentTargets, type CloudSkill, type NotisSyncState } from './types';
+import { normalizeAgentTargets, type AgentTargets, type SkillSyncFailure, type CloudSkill, type NotisSyncState } from './types';
 
 const HOME_DIR = os.homedir();
 
@@ -22,6 +22,22 @@ type ExternalAgent = keyof typeof EXTERNAL_AGENT_SKILL_DIRS;
 
 const EXTERNAL_AGENTS = Object.keys(EXTERNAL_AGENT_SKILL_DIRS) as ExternalAgent[];
 
+const AGENT_FAILURE_LABELS: Record<string, string> = {
+  claude_code: 'Claude Code',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  legacy: 'legacy ~/.agents/skills',
+};
+
+/** Failures are shown next to skill names in the Portal and CLI; never leak raw agent ids. */
+function agentFailureLabel(agent: string): string {
+  return AGENT_FAILURE_LABELS[agent] ?? agent;
+}
+
+function agentFolderFailureName(agent: string): string {
+  return `${agentFailureLabel(agent)} skills folder`;
+}
+
 export interface DeletedAgentSymlink {
   skillId: string;
   skillName: string;
@@ -46,6 +62,8 @@ export interface SymlinkSyncResult {
   linked: number;
   removed: number;
   skipped: number;
+  verifiedAgentLinks?: Record<string, Partial<AgentTargets>>;
+  failures?: SkillSyncFailure[];
 }
 
 /** Remove only links into another account's managed mirror. This is safe even
@@ -128,8 +146,9 @@ async function isManagedSymlink(linkPath: string, managedRoots: string[]): Promi
     return managedRoots.some((root) => (
       resolvedTarget === root || resolvedTarget.startsWith(`${root}${path.sep}`)
     ));
-  } catch {
-    return false;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return false;
+    throw error;
   }
 }
 
@@ -146,8 +165,8 @@ async function ensureCorrectSymlink(linkPath: string, targetPath: string): Promi
     } else {
       return 'blocked';
     }
-  } catch {
-    // Missing path is expected.
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;
   }
 
   const relativePath = path.relative(path.dirname(linkPath), targetPath);
@@ -166,6 +185,8 @@ async function removeUndesiredManagedSymlinks(
   agentDir: string,
   desiredSkills: Set<string>,
   managedRoots: string[],
+  failures: SkillSyncFailure[],
+  agent: string,
 ): Promise<number> {
   let removed = 0;
   try {
@@ -173,13 +194,19 @@ async function removeUndesiredManagedSymlinks(
     const existingEntries = await fs.readdir(agentDir, { withFileTypes: true });
     for (const entry of existingEntries) {
       const entryPath = path.join(agentDir, entry.name);
-      if (!desiredSkills.has(entry.name) && await isManagedSymlink(entryPath, managedRoots)) {
-        await fs.unlink(entryPath);
-        removed += 1;
+      try {
+        if (!desiredSkills.has(entry.name) && await isManagedSymlink(entryPath, managedRoots)) {
+          await fs.unlink(entryPath);
+          removed += 1;
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+          failures.push({ name: entry.name, error: `${agentFailureLabel(agent)}: could not remove skill link (${(error as Error).message})` });
+        }
       }
     }
-  } catch {
-    // Missing or unreadable agent directories should not block skill sync.
+  } catch (error) {
+    failures.push({ name: agentFolderFailureName(agent), error: `Could not read agent skills directory (${(error as Error).message})` });
   }
   return removed;
 }
@@ -255,7 +282,9 @@ export async function detectDeletedAgentSymlinks(
         continue;
       }
       const previous = previousState.skills[skill.name];
-      if (!previous) {
+      if (!previous || previous.cloudId !== skill.id
+        || previous.verifiedAgentLinks?.[agent] !== true
+        || !skill.updated_at || previous.cloudUpdatedAt !== skill.updated_at) {
         continue;
       }
 
@@ -293,10 +322,12 @@ export async function syncSymlinks(
 ): Promise<SymlinkSyncResult> {
   await fs.mkdir(skillsDir, { recursive: true });
 
-  const result: SymlinkSyncResult = {
+  const result: Required<SymlinkSyncResult> = {
     linked: 0,
     removed: 0,
     skipped: 0,
+    verifiedAgentLinks: {},
+    failures: [],
   };
   const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
   const legacyGlobalSkillsDir = options.legacyGlobalSkillsDir || LEGACY_AGENTS_SKILLS_DIR;
@@ -336,23 +367,36 @@ export async function syncSymlinks(
       continue;
     }
 
-    await fs.mkdir(agentDir, { recursive: true });
+    try {
+      await fs.mkdir(agentDir, { recursive: true });
+    } catch (error) {
+      result.failures.push({ name: agentFolderFailureName(agent), error: `Could not create agent skills directory (${(error as Error).message})` });
+      continue;
+    }
 
     const desiredSkills = desiredByAgent[agent];
     if (options.removeUndesired !== false) {
-      result.removed += await removeUndesiredManagedSymlinks(agentDir, desiredSkills, managedRoots);
+      result.removed += await removeUndesiredManagedSymlinks(agentDir, desiredSkills, managedRoots, result.failures, agent);
     }
 
     for (const skillName of desiredSkills) {
       const targetPath = path.join(skillsDir, skillName);
       const linkPath = path.join(agentDir, safeName(skillName, agentDir));
       try {
-        await fs.access(targetPath);
+        if (!(await fs.stat(path.join(targetPath, "SKILL.md"))).isFile()) throw new Error("Missing SKILL.md");
       } catch {
         result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: SKILL.md is missing or unreadable` });
+        continue;
+      }
+      let syncOutcome;
+      try {
+        syncOutcome = await ensureCorrectSymlink(linkPath, targetPath);
+      } catch (error) {
+        result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: could not create skill link (${(error as Error).message})` });
         continue;
       }
-      const syncOutcome = await ensureCorrectSymlink(linkPath, targetPath);
       if (syncOutcome === 'linked') {
         result.linked += 1;
       } else if (syncOutcome === 'blocked') {
@@ -360,9 +404,13 @@ export async function syncSymlinks(
           `[skill-sync] Could not link "${skillName}" for ${agent}: non-symlink entry blocks ${linkPath}`,
         );
         result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: an existing file or folder blocks the skill link` });
       } else {
         result.skipped += 1;
       }
+      if (syncOutcome !== "blocked") {
+        result.verifiedAgentLinks[skillName] = { ...result.verifiedAgentLinks[skillName], [agent]: true };
+      }
     }
   }
 
@@ -376,6 +424,8 @@ export async function syncSymlinks(
       legacyGlobalSkillsDir,
       new Set(),
       managedRoots,
+      result.failures,
+      'legacy',
     );
   }